Documentation
¶
Overview ¶
Package swagger provides automatic OpenAPI 3.0 spec generation from chok's typed handler system. Route registration and spec collection happen in a single call — zero annotations required.
Index ¶
- func Action[T any](doc *Spec, rg *gin.RouterGroup, method, path string, h handler.ActionFunc[T], ...)
- func Get[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], ...)
- func List[T any](doc *Spec, rg *gin.RouterGroup, path string, lister handler.QueryLister[T], ...)
- func Patch[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], ...)
- func Populate(spec *Spec, engine *gin.Engine)
- func Post[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], ...)
- func Put[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], ...)
- type Op
- type Parameter
- type Schema
- type Spec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Action ¶
func Action[T any](doc *Spec, rg *gin.RouterGroup, method, path string, h handler.ActionFunc[T], op Op)
Action registers a route for ActionFunc (no response body) and adds it to the spec.
func Get ¶
func Get[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], op Op)
Get registers a GET route and adds it to the OpenAPI spec.
func List ¶
func List[T any](doc *Spec, rg *gin.RouterGroup, path string, lister handler.QueryLister[T], op Op)
List registers a GET list route using HandleList and adds it to the spec. The response schema is automatically wrapped in ListResult[T].
func Patch ¶
func Patch[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], op Op)
Patch registers a PATCH route and adds it to the OpenAPI spec.
func Populate ¶
Populate walks the gin engine's registered routes, looks up handler metadata (registered by HandleRequest/HandleAction/HandleList), and adds the corresponding OpenAPI operations to spec. Nil-safe on both arguments; safe to call more than once (later calls add new routes).
func Post ¶
func Post[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], op Op)
Post registers a POST route and adds it to the OpenAPI spec.
func Put ¶
func Put[T, R any](doc *Spec, rg *gin.RouterGroup, path string, h handler.HandlerFunc[T, R], op Op)
Put registers a PUT route and adds it to the OpenAPI spec.
Types ¶
type Op ¶
type Op struct {
Summary string
Description string
Tags []string
Code int // success status code override
Deprecated bool
Public bool // true = no auth required
}
Op configures a single OpenAPI operation.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"` // path, query
Required bool `json:"required,omitempty"`
Schema *Schema `json:"schema,omitempty"`
}
Parameter is an OpenAPI Parameter Object.
type Schema ¶
type Schema struct {
Type string `json:"type,omitempty"`
Format string `json:"format,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Items *Schema `json:"items,omitempty"`
AdditionalProps *Schema `json:"additionalProperties,omitempty"`
Required []string `json:"required,omitempty"`
Enum []string `json:"enum,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
MinLength *int `json:"minLength,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
Nullable bool `json:"nullable,omitempty"`
}
Schema is a simplified OpenAPI 3.0 Schema Object.
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec collects OpenAPI metadata during route registration.
func Generate ¶
func Generate(opts *config.SwaggerOptions, engine *gin.Engine) *Spec
Generate walks the gin engine's registered routes, looks up handler metadata (registered automatically by HandleRequest/HandleAction/HandleList), and builds a complete OpenAPI 3.0 spec. Returns nil if not enabled.
This approach requires ZERO changes to route registration code:
// Routes registered normally:
rg.POST("/posts", handler.HandleRequest(h.create, handler.WithSuccessCode(201)))
rg.GET("/posts", handler.HandleList[model.Post](posts))
// One line generates the spec:
swagger.Generate(&cfg.Swagger, srv.Engine())
func Setup ¶
func Setup(opts *config.SwaggerOptions, r interface { GET(string, ...gin.HandlerFunc) gin.IRoutes }) *Spec
Setup creates a Spec from config, applies BearerAuth if configured, and mounts the swagger UI — all in one call. Returns nil if not enabled.
doc := swagger.Setup(&cfg.Swagger, srv.Engine())
swagger.Post(doc, api, "/posts", h.create, swagger.Op{...})
func (*Spec) BearerAuth ¶
func (s *Spec) BearerAuth()
BearerAuth declares a JWT Bearer security scheme. All operations added after this call require authentication by default. Set Op.Public = true for public endpoints. Nil-safe: no-op when Spec is nil (swagger disabled).
func (*Spec) MarshalJSON ¶
MarshalJSON outputs the full OpenAPI 3.0 spec. Nil-safe: returns "null".