Documentation
¶
Overview ¶
Package openapi generates an OpenAPI 3.1 document from the router: typed routes (api.Register) are described from their input and output types and `validate` tags; plain routes get a generic entry.
doc := openapi.Generate(r.Routes(), openapi.Info{Title: "Shop", Version: "1.0.0"})
See https://github.com/AlexGalhardo/vukem/blob/main/docs/api.md.
Index ¶
- Variables
- func GoClient(d *Document, pkg string) ([]byte, error)
- func TypeScript(d *Document, zod bool) (string, error)
- func TypeScriptClient(d *Document) (string, error)
- type Components
- type Document
- type Field
- type Info
- type MediaType
- type Operation
- type Parameter
- type RequestBody
- type Response
- type Schema
- type Schemas
- type Skip
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoOperation = errors.New("openapi: no operation matches the request")
ErrNoOperation is returned when the document has no operation for the request.
Functions ¶
func GoClient ¶ added in v0.19.0
GoClient returns gofmt'd Go source for a stdlib-only client in package pkg: one type per component schema, <Operation>Body, <Operation>Query and <Operation>Response for inline schemas, and a Client with one method per operation with an operationId. Path parameters are typed arguments; any non-2xx response becomes an *Error carrying the RFC 9457 problem.
Mapping: objects are structs (optional fields get omitempty, optional or nullable scalars and structs are pointers), additionalProperties maps, string enums named string types with constants, date-time strings time.Time, integers int64, numbers float64, and unions json.RawMessage.
func TypeScript ¶
TypeScript returns TypeScript declarations for the document: one type per component schema, plus <Operation>Body, <Operation>Query and <Operation>Response for every operation with an operationId. With zod set, Zod schemas (<Name>Schema) for the components follow the types.
func TypeScriptClient ¶ added in v0.19.0
TypeScriptClient returns a dependency-free TypeScript client for the document: the TypeScript types (without Zod), <Operation>Params for path parameters, ApiError and createClient, which has one async method per operation with an operationId (camelCase: "products.store" becomes productsStore). It needs fetch, URLSearchParams and Headers, so it runs in browsers and Node 18+.
Types ¶
type Components ¶
type Components struct {
Schemas map[string]Schema `json:"schemas,omitempty"`
Responses map[string]Response `json:"responses,omitempty"`
SecuritySchemes map[string]Schema `json:"securitySchemes,omitempty"`
}
Components holds reusable schemas, responses and security schemes.
type Document ¶
type Document struct {
OpenAPI string `json:"openapi"`
Info docInfo `json:"info"`
Servers []server `json:"servers,omitempty"`
Paths map[string]map[string]*Operation `json:"paths"`
Components Components `json:"components"`
}
Document is an OpenAPI 3.1 document.
func Generate ¶
Generate builds the document for routes (router.Routes()).
Example ¶
package main
import (
"fmt"
"github.com/AlexGalhardo/vukem/api"
"github.com/AlexGalhardo/vukem/openapi"
"github.com/AlexGalhardo/vukem/router"
"github.com/AlexGalhardo/vukem/web"
)
type exShowProduct struct {
ID int `json:"id"`
}
type exProduct struct {
ID int `json:"id"`
Name string `json:"name"`
}
func main() {
r := router.New(nil)
api.Register(r, "GET /api/products/{id}", api.Op{Name: "products.show", Summary: "Show a product"},
func(_ *web.Ctx, in exShowProduct) (exProduct, error) {
return exProduct{ID: in.ID}, nil
})
doc := openapi.Generate(r.Routes(), openapi.Info{Title: "Shop", Version: "1.0.0"})
op := doc.Paths["/api/products/{id}"]["get"]
fmt.Println(doc.OpenAPI, op.OperationID, op.Summary)
}
Output: 3.1.0 products.show Show a product
func (*Document) ValidateResponse ¶
ValidateResponse checks a response body against the document: the operation for method and path (a concrete URL path), then the schema declared for status, or the "default" response. It supports the JSON Schema subset Generate emits.
type Info ¶
type Info struct {
Title string
Version string
Description string
Servers []string
// PathPrefix keeps only routes under it (e.g. "/api"); empty keeps all.
PathPrefix string
// SecuritySchemes adds or replaces schemes; "bearer" (HTTP bearer
// token) is predefined.
SecuritySchemes map[string]Schema
}
Info configures the document.
type MediaType ¶
type MediaType struct {
Schema Schema `json:"schema"`
}
MediaType wraps a schema for one content type.
type Operation ¶
type Operation struct {
OperationID string `json:"operationId,omitempty"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Tags []string `json:"tags,omitempty"`
Deprecated bool `json:"deprecated,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses map[string]Response `json:"responses"`
Security []map[string][]string `json:"security,omitempty"`
}
Operation is one method on a path.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"`
Required bool `json:"required,omitempty"`
Description string `json:"description,omitempty"`
Schema Schema `json:"schema"`
}
Parameter is a path or query parameter.
type RequestBody ¶
type RequestBody struct {
Required bool `json:"required"`
Content map[string]MediaType `json:"content"`
}
RequestBody is an operation's body.
type Response ¶
type Response struct {
Ref string `json:"$ref,omitempty"`
Description string `json:"description,omitempty"`
Content map[string]MediaType `json:"content,omitempty"`
}
Response is a response or a $ref to a shared one.
type Schemas ¶
type Schemas struct {
// contains filtered or unexported fields
}
Schemas turns Go types into JSON Schemas, collecting named structs as reusable components. Constraints come from the same `validate` tags the z package enforces, so the document matches what the server accepts.
func (*Schemas) Components ¶
Components returns the named schemas collected so far.
Source Files