doc

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: May 2, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package doc contains OpenAPI documentation metadata, schema generation, and handlers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func OpenAPIHandler 

func OpenAPIHandler(docs *Docs) http.HandlerFunc

OpenAPIHandler returns a handler that serves the docs as OpenAPI JSON.

func RegisterExporter 

func RegisterExporter(name string, exporter Exporter)

RegisterExporter registers a documentation UI exporter.

func SwaggerUIHandler 

func SwaggerUIHandler(openAPIURL string) http.HandlerFunc

SwaggerUIHandler returns a handler that serves Swagger UI for an OpenAPI URL.

Types

type API 

type API struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

API contains the public API metadata rendered into OpenAPI.

type Components 

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

Components contains reusable OpenAPI components.

type DataType 

type DataType string

DataType describes primitive route parameter types. 

const (
	String DataType = "string"
	Int    DataType = "integer"
	Float  DataType = "number"
	Bool   DataType = "boolean"
)

type Docs 

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

Docs stores route metadata for OpenAPI generation.

func New 

func New(info API) *Docs

New creates an OpenAPI documentation collector.

func (*Docs) API 

func (docs *Docs) API() API

API returns the docs API metadata.

func (*Docs) AddSecurityScheme 

func (docs *Docs) AddSecurityScheme(name string, scheme SecurityScheme)

AddSecurityScheme registers a reusable OpenAPI security scheme.

func (*Docs) Register 

func (docs *Docs) Register(method string, path string, opts ...RouteOption) Route

Register stores a route and applies its declarative options.

func (*Docs) Routes 

func (docs *Docs) Routes() []Route

Routes returns a snapshot of registered routes.

func (*Docs) SecuritySchemes 

func (docs *Docs) SecuritySchemes() map[string]SecurityScheme

SecuritySchemes returns a snapshot of configured security schemes.

type Exporter 

type Exporter interface {
	Handler(openAPIURL string) http.HandlerFunc
}

Exporter serves documentation UI for an OpenAPI URL.

func ExporterByName 

func ExporterByName(name string) (Exporter, error)

ExporterByName returns a registered documentation UI exporter.

type MediaType 

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

MediaType is an OpenAPI media type object.

type OpenAPI 

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

OpenAPI is the generated OpenAPI 3 document.

func GenerateOpenAPI 

func GenerateOpenAPI(docs *Docs) OpenAPI

GenerateOpenAPI renders an OpenAPI 3.0 document from a docs.

type OpenAPIHeader 

type OpenAPIHeader struct {
	Description string  `json:"description,omitempty"`
	Schema      *Schema `json:"schema,omitempty"`
}

OpenAPIHeader is an OpenAPI header object.

type OpenAPIParameter 

type OpenAPIParameter struct {
	Name        string  `json:"name"`
	In          string  `json:"in"`
	Required    bool    `json:"required,omitempty"`
	Description string  `json:"description,omitempty"`
	Schema      *Schema `json:"schema,omitempty"`
}

OpenAPIParameter is an OpenAPI parameter object.

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"`
	Parameters  []OpenAPIParameter        `json:"parameters,omitempty"`
	RequestBody *RequestBodyObject        `json:"requestBody,omitempty"`
	Responses   map[string]ResponseObject `json:"responses"`
	Security    []map[string][]string     `json:"security,omitempty"`
}

Operation is an OpenAPI operation object.

type Parameter 

type Parameter struct {
	Name        string
	In          string
	Type        DataType
	Required    bool
	Description string
	Schema      *Schema
}

Parameter describes a query, path, header, or cookie parameter.

type RequestBodyObject 

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

RequestBodyObject is an OpenAPI requestBody object.

type ResponseHeaderInfo 

type ResponseHeaderInfo struct {
	Name        string
	Type        DataType
	Description string
	Schema      *Schema
}

ResponseHeaderInfo describes a documented response header.

func ResponseHeader 

func ResponseHeader(name string, typ DataType, description string) ResponseHeaderInfo

ResponseHeader documents a header returned by a response.

type ResponseObject 

type ResponseObject struct {
	Description string                   `json:"description"`
	Headers     map[string]OpenAPIHeader `json:"headers,omitempty"`
	Content     map[string]MediaType     `json:"content,omitempty"`
}

ResponseObject is an OpenAPI response object.

type Route 

type Route struct {
	Method      string
	Path        string
	OperationID string
	Summary     string
	Description string
	Tags        []string
	Body        interface{}
	BodySchema  *Schema
	BodyExample interface{}
	Responses   []RouteResponse
	Parameters  []Parameter
	Security    []string
}

Route describes a registered HTTP operation.

type RouteOption 

type RouteOption func(*Route)

RouteOption mutates route metadata.

func Body 

func Body(body interface{}) RouteOption

Body sets the request body model inferred with reflection.

func BodySchema 

func BodySchema(schema *Schema) RouteOption

BodySchema sets a manual request body schema.

func BodyWithExample 

func BodyWithExample(body interface{}, example interface{}) RouteOption

BodyWithExample sets the request body model and an OpenAPI media type example.

func Description 

func Description(description string) RouteOption

Description sets the OpenAPI operation description. 

func Header(name string, typ DataType, required bool) RouteOption

Header adds a request header parameter.

func HeaderWithDescription 

func HeaderWithDescription(name string, typ DataType, required bool, description string) RouteOption

HeaderWithDescription adds a request header parameter with an OpenAPI description.

func OperationID 

func OperationID(id string) RouteOption

OperationID sets the OpenAPI operationId used by client generators.

func Path 

func Path(name string, typ DataType, required bool) RouteOption

Path adds a path parameter.

func PathWithDescription 

func PathWithDescription(name string, typ DataType, required bool, description string) RouteOption

PathWithDescription adds a path parameter with an OpenAPI description.

func Query 

func Query(name string, typ DataType, required bool) RouteOption

Query adds a query parameter.

func QueryWithDescription 

func QueryWithDescription(name string, typ DataType, required bool, description string) RouteOption

QueryWithDescription adds a query parameter with an OpenAPI description.

func Responds 

func Responds(status int, body interface{}) RouteOption

Responds adds a response model for a status code.

func ResponseSchema 

func ResponseSchema(status int, description string, schema *Schema) RouteOption

ResponseSchema adds a response with a manual schema.

func ResponseWithDescription 

func ResponseWithDescription(status int, description string, body interface{}) RouteOption

ResponseWithDescription adds a response model and description.

func ResponseWithDescriptionAndExample 

func ResponseWithDescriptionAndExample(status int, description string, body interface{}, example interface{}, headers ...ResponseHeaderInfo) RouteOption

ResponseWithDescriptionAndExample adds a response model, description, example, and optional headers.

func Security 

func Security(name string) RouteOption

Security adds a named security requirement to the operation.

func Status 

func Status(status int, body interface{}) RouteOption

Status adds a response model for a status code.

func StatusWithExample 

func StatusWithExample(status int, body interface{}, example interface{}, headers ...ResponseHeaderInfo) RouteOption

StatusWithExample adds a response model and an OpenAPI media type example.

func StatusWithHeaders 

func StatusWithHeaders(status int, body interface{}, headers ...ResponseHeaderInfo) RouteOption

StatusWithHeaders adds a response model and documented response headers.

func Summary 

func Summary(summary string) RouteOption

Summary sets the OpenAPI operation summary.

func Tags 

func Tags(tags ...string) RouteOption

Tags sets the OpenAPI operation tags.

type RouteResponse 

type RouteResponse struct {
	Status      int
	Description string
	Body        interface{}
	Schema      *Schema
	Example     interface{}
	Headers     []ResponseHeaderInfo
}

RouteResponse describes an HTTP response for an operation.

type Router 

type Router interface {
	Handle(method string, path string, handler http.HandlerFunc, opts ...RouteOption)
}

Router is the minimal contract implemented by documentation-aware router adapters.

func NewRouter 

func NewRouter(docs *Docs) Router

NewRouter creates a router useful for tests and documentation-only registration.

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"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Description          string             `json:"description,omitempty"`
	Enum                 []interface{}      `json:"enum,omitempty"`
	Nullable             bool               `json:"nullable,omitempty"`
	Ref                  string             `json:"$ref,omitempty"`
	Example              interface{}        `json:"example,omitempty"`
}

Schema is a small OpenAPI schema object.

func SchemaFromType 

func SchemaFromType(value interface{}) *Schema

SchemaFromType infers an OpenAPI schema from a Go value or reflect.Type.

type SecurityScheme 

type SecurityScheme struct {
	Type         string `json:"type"`
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
	Name         string `json:"name,omitempty"`
	In           string `json:"in,omitempty"`
}

SecurityScheme is an OpenAPI security scheme object.

func APIKeySecurity 

func APIKeySecurity(name string, in string) SecurityScheme

APIKeySecurity returns an API key security scheme.

func BasicSecurity 

func BasicSecurity() SecurityScheme

BasicSecurity returns an HTTP basic security scheme.

func BearerSecurity 

func BearerSecurity(format string) SecurityScheme

BearerSecurity returns an HTTP bearer security scheme.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.