openapi

Documentation

Overview

Package openapi generates OpenAPI 3.1 documents from plain Go types: the same struct tags that drive github.com/libtnb/validator (validate, json, uri, query) become schemas, parameters and constraints — the validation rules are the documentation, so the two can never drift apart.

g := openapi.New("my-api", "1.0.0")
g.Add(http.MethodPost, "/users", openapi.Op{
    Summary:  "Create a user",
    Request:  request.UserAdd{},   // validate:"required && min:3" -> minLength: 3
    Response: biz.User{},
})
blob, _ := g.JSON()

Index

• func DocsHTML(title, specURL string) []byte
• type Components
• type Document
• type Generator
  • func New(title, version string, opts ...Option) *Generator
  • func (g *Generator) Add(method, path string, op Op) error
  • func (g *Generator) Document() *Document
  • func (g *Generator) JSON() ([]byte, error)
• type Info
• type MediaType
• type Op
• type Operation
• type Option
  • func WithType(sample any, s *Schema) Option
  • func WithValidator(v *validator.Validator) Option
• type Parameter
• type PathItem
• type RequestBody
• type Response
• type Schema

Functions

func DocsHTML

func DocsHTML(title, specURL string) []byte

DocsHTML returns a self-contained documentation page rendering the spec at specURL with Scalar (https://github.com/scalar/scalar).

Types

type Components

type Components struct {
	Schemas map[string]*Schema `json:"schemas,omitempty"`
}

type Document

type Document struct {
	OpenAPI    string              `json:"openapi"`
	Info       Info                `json:"info"`
	Paths      map[string]PathItem `json:"paths,omitempty"`
	Components *Components         `json:"components,omitempty"`
}

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator accumulates operations into an OpenAPI 3.1 document. It is not safe for concurrent use; build the document from one goroutine.

func New

func New(title, version string, opts ...Option) *Generator

func (*Generator) Add

func (g *Generator) Add(method, path string, op Op) error

Add registers an operation under an OAS-style path ("/users/{id}").

func (*Generator) Document

func (g *Generator) Document() *Document

Document returns the assembled document.

func (*Generator) JSON

func (g *Generator) JSON() ([]byte, error)

JSON marshals the document, indented for humans and diffs.

type Info

type Info struct {
	Title   string `json:"title"`
	Version string `json:"version"`
}

type MediaType

type MediaType struct {
	Schema *Schema `json:"schema,omitempty"`
}

type Op

type Op struct {
	Summary  string
	Tags     []string
	Request  any // uri tags -> path params, query tags -> query params, json tags -> body
	Response any // the 200-response body; nil means no content
	Status   int // response status, default 200
}

Op describes one operation. Request and Response are sample values (or zero structs); their types drive everything else.

type Operation

type Operation struct {
	Summary     string               `json:"summary,omitempty"`
	Tags        []string             `json:"tags,omitempty"`
	Parameters  []*Parameter         `json:"parameters,omitempty"`
	RequestBody *RequestBody         `json:"requestBody,omitempty"`
	Responses   map[string]*Response `json:"responses"`
}

type Option

type Option func(*Generator)

func WithType

func WithType(sample any, s *Schema) Option

WithType overrides the schema of a type the reflector cannot guess, e.g. WithType(carbon.DateTime{}, &Schema{Type: "string", Format: "date-time"}).

func WithValidator

func WithValidator(v *validator.Validator) Option

WithValidator uses v to introspect validation rules. Default: the package-level default validator.

type Parameter

type Parameter struct {
	Name     string  `json:"name"`
	In       string  `json:"in"` // "path" or "query"
	Required bool    `json:"required,omitempty"`
	Schema   *Schema `json:"schema,omitempty"`
}

type PathItem

type PathItem map[string]*Operation

PathItem maps a lowercase HTTP method to its operation.

type RequestBody

type RequestBody struct {
	Required bool                  `json:"required,omitempty"`
	Content  map[string]*MediaType `json:"content"`
}

type Response

type Response struct {
	Description string                `json:"description"`
	Content     map[string]*MediaType `json:"content,omitempty"`
}

type Schema

type Schema struct {
	Ref                  string             `json:"$ref,omitempty"`
	Type                 string             `json:"type,omitempty"`
	Format               string             `json:"format,omitempty"`
	Description          string             `json:"description,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Enum                 []any              `json:"enum,omitempty"`
	Pattern              string             `json:"pattern,omitempty"`
	Minimum              *float64           `json:"minimum,omitempty"`
	Maximum              *float64           `json:"maximum,omitempty"`
	ExclusiveMinimum     *float64           `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     *float64           `json:"exclusiveMaximum,omitempty"`
	MinLength            *uint64            `json:"minLength,omitempty"`
	MaxLength            *uint64            `json:"maxLength,omitempty"`
	MinItems             *uint64            `json:"minItems,omitempty"`
	MaxItems             *uint64            `json:"maxItems,omitempty"`
	UniqueItems          bool               `json:"uniqueItems,omitempty"`
	// ContentEncoding marks base64 payloads ([]byte fields), per JSON Schema 2020-12.
	ContentEncoding string `json:"contentEncoding,omitempty"`
}

Schema is the JSON Schema subset used by both parameters and bodies.