Documentation
¶
Overview ¶
Package openapi generates OpenAPI 3 specifications from struct types that implement [apivalidation.Ruler]. It also provides helpers for registering endpoints and serving Swagger UI.
Use DocBase to create a base document, register endpoints with Get, Post, Put, Patch, or Delete, and serve the Swagger UI with SwaggerHandlerMust:
doc := openapi.DocBase("my-api", "My API", "1.0")
openapi.Post(doc, "/orders", "createOrder", openapi.Endpoint{
Request: Order{},
Response: Order{},
})
http.Handle("/swagger/", openapi.SwaggerHandlerMust("/swagger/", doc))
Index ¶
- func AddPath(path, method string, s *openapi3.T, op *openapi3.Operation)
- func Delete(doc *openapi3.T, path, operationID string, ep Endpoint)
- func DocBase(serviceName, description, version string) *openapi3.T
- func Get(doc *openapi3.T, path, operationID string, ep Endpoint)
- func NewRequest(vs ...any) (*openapi3.RequestBodyRef, error)
- func NewRequestMust(vs ...any) *openapi3.RequestBodyRef
- func NewResponse(vs map[string]Response) (*openapi3.Responses, error)
- func NewResponseMust(vs map[string]Response) *openapi3.Responses
- func NewSchemaRefForValue(value any) (*openapi3.SchemaRef, error)
- func Patch(doc *openapi3.T, path, operationID string, ep Endpoint)
- func Post(doc *openapi3.T, path, operationID string, ep Endpoint)
- func Put(doc *openapi3.T, path, operationID string, ep Endpoint)
- func SwaggerHandler(prefix string, s *openapi3.T) (http.Handler, error)
- func SwaggerHandlerMust(prefix string, s *openapi3.T) http.Handler
- type Endpoint
- type Response
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DocBase ¶
DocBase returns a basic OpenAPI 3.0.3 document structure.
Example ¶
package main
import (
"fmt"
"github.com/Gobd/apivalidation/openapi"
)
func main() {
doc := openapi.DocBase("My Service", "A cool service", "0.1.0")
fmt.Println(doc.Info.Title)
fmt.Println(doc.OpenAPI)
}
Output: My Service 3.0.3
func Get ¶
Get registers a GET endpoint on doc.
Example ¶
package main
import (
"fmt"
v "github.com/Gobd/apivalidation"
"github.com/Gobd/apivalidation/openapi"
)
type Item struct {
Name string `json:"name"`
Price float64 `json:"price"`
}
func (it *Item) Rules() []*v.FieldRules {
return []*v.FieldRules{
v.Field(&it.Name, v.Required, v.Length(1, 200)),
v.Field(&it.Price, v.Required, v.Min(0.01)),
}
}
func main() {
doc := openapi.DocBase("Shop API", "Example API", "1.0.0")
openapi.Get(doc, "/items", "listItems", openapi.Endpoint{
Summary: "List all items",
Response: []Item{},
})
fmt.Println(doc.Paths.Value("/items").Get.OperationID)
}
Output: listItems
func NewRequest ¶
func NewRequest(vs ...any) (*openapi3.RequestBodyRef, error)
NewRequest generates an OpenAPI request body schema from the given value types.
func NewRequestMust ¶
func NewRequestMust(vs ...any) *openapi3.RequestBodyRef
NewRequestMust is like NewRequest but panics on error.
func NewResponse ¶
NewResponse creates an OpenAPI responses object. Map key is status code (e.g. "200", "4xx").
func NewResponseMust ¶
NewResponseMust is like NewResponse but panics on error. Map key is status code (e.g. "200", "4xx").
func NewSchemaRefForValue ¶
NewSchemaRefForValue generates an OpenAPI schema for the given value, applying validation rules from types that implement [apivalidation.Ruler], [apivalidation.ContextRuler], or [apivalidation.ValueRuler].
func Post ¶
Post registers a POST endpoint on doc.
Example ¶
package main
import (
"fmt"
v "github.com/Gobd/apivalidation"
"github.com/Gobd/apivalidation/openapi"
)
type Item struct {
Name string `json:"name"`
Price float64 `json:"price"`
}
func (it *Item) Rules() []*v.FieldRules {
return []*v.FieldRules{
v.Field(&it.Name, v.Required, v.Length(1, 200)),
v.Field(&it.Price, v.Required, v.Min(0.01)),
}
}
func main() {
doc := openapi.DocBase("Shop API", "Example API", "1.0.0")
openapi.Post(doc, "/items", "createItem", openapi.Endpoint{
Summary: "Create an item",
Request: Item{},
Response: Item{},
})
fmt.Println(doc.Paths.Value("/items").Post.OperationID)
}
Output: createItem
func SwaggerHandler ¶
SwaggerHandler returns an http.Handler that serves the Swagger UI for the given OpenAPI spec. The prefix is stripped automatically, so just mount it:
http.Handle("/swagger/", openapi.SwaggerHandlerMust("/swagger/", spec))
func SwaggerHandlerMust ¶
SwaggerHandlerMust is like SwaggerHandler but panics on error.
Types ¶
type Endpoint ¶
type Endpoint struct {
Summary string
Description string
Request any // single request body type (convenience)
Requests []any // multiple request body types (oneOf)
Response any // single 200 response type (convenience)
Responses map[string]Response // full response map (overrides Response if both set)
}
Endpoint describes a single API operation for the convenience helpers Get, Post, Put, Patch, and Delete.
Source Files