swagger

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 19, 2026 License: MIT Imports: 11 Imported by: 0

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

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

func Populate(spec *Spec, engine *gin.Engine)

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 New

func New(title, version string) *Spec

New creates an OpenAPI spec builder.

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

func (s *Spec) MarshalJSON() ([]byte, error)

MarshalJSON outputs the full OpenAPI 3.0 spec. Nil-safe: returns "null".

func (*Spec) Mount

func (s *Spec) Mount(r interface {
	GET(string, ...gin.HandlerFunc) gin.IRoutes
}, prefix string)

Mount registers swagger UI and spec JSON on the server.

doc.Mount(srv, "/swagger")

Serves:

GET /swagger/doc.json — OpenAPI JSON
GET /swagger/          — Swagger UI

Mount registers swagger UI and spec JSON on the server. Nil-safe: no-op when Spec is nil (swagger disabled).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL