openapi

README

Fox OpenAPI

OpenAPI 3.0.3 generator and CLI for Fox.

The recommended workflow is fox-openapi: expose a function that builds a *fox.Engine, then generate a committed openapi.yaml during development or CI. Business code does not need to mount OpenAPI handlers or import this module unless it uses the optional metadata hook.

Install

go install github.com/fox-gonic/openapi/cmd/fox-openapi@latest

Quickstart

Create fox-openapi.yaml in your application root:

entry: github.com/acme/myapp/internal/server.NewEngine
out: api/openapi.yaml
sources:
  - ./...
info:
  title: Acme API
  version: 1.0.0

Then run:

fox-openapi generate
fox-openapi check
fox-openapi serve --addr 127.0.0.1:8765

serve exposes /openapi.yaml, /openapi.json, /docs, /scalar, and /redoc with embedded offline UI assets.

See cmd/fox-openapi/README.md for CLI details and docs/openapi.md for library usage.

Documentation

Overview

Package openapi generates OpenAPI specs from Fox routes and handler signatures.

Index

• func ApplySpecMetadata(spec *openapi3.T, metadata SpecMetadata)
• func HTTPBearerSecurity(description string) *openapi3.SecurityScheme
• func JSONHandler(g *Generator) fox.HandlerFunc
• func MarshalSpecJSON(spec *openapi3.T) ([]byte, error)
• func MarshalSpecYAML(spec *openapi3.T) ([]byte, error)
• func Mount(router Router, g *Generator, opts ...MountOption)
• func YAMLHandler(g *Generator) fox.HandlerFunc
• type Generator
  • func New(engine *fox.Engine, opts ...Option) *Generator
  • func (g *Generator) JSON() ([]byte, error)
  • func (g *Generator) Regenerate()
  • func (g *Generator) Spec() *openapi3.T
  • func (g *Generator) Warnings() []string
  • func (g *Generator) WriteYAML(w io.Writer) error
  • func (g *Generator) YAML() ([]byte, error)
• type MountOption
  • func MountJSON(path string) MountOption
  • func MountYAML(path string) MountOption
• type OAuthFlowConfig
• type OAuthFlowsConfig
• type OperationOption
  • func Deprecated(value bool) OperationOption
  • func Description(value string) OperationOption
  • func OperationID(value string) OperationOption
  • func Response(status int, body any, description string) OperationOption
  • func Security(name string, scopes ...string) OperationOption
  • func Summary(value string) OperationOption
  • func Tags(values ...string) OperationOption
• type Option
  • func Group(prefix string, opts ...OperationOption) Option
  • func Info(title, version string) Option
  • func Operation(method, path string, opts ...OperationOption) Option
  • func RegisterFormatter(typ reflect.Type, schema *openapi3.Schema) Option
  • func SecurityScheme(name string, scheme *openapi3.SecurityScheme) Option
  • func SecuritySchemeFromConfig(name string, scheme SecuritySchemeConfig) Option
  • func Server(url string) Option
  • func SetErrorSchema(body any) Option
  • func Source(paths []string, opts ...SourceOption) Option
• type Router
• type SecuritySchemeConfig
• type SourceOption
  • func IncludeTestFiles() SourceOption
• type SpecExternalDocs
• type SpecMetadata
• type SpecTag

Functions

func ApplySpecMetadata

func ApplySpecMetadata(spec *openapi3.T, metadata SpecMetadata)

ApplySpecMetadata applies top-level metadata to a generated OpenAPI model.

func HTTPBearerSecurity

func HTTPBearerSecurity(description string) *openapi3.SecurityScheme

HTTPBearerSecurity creates an HTTP bearer security scheme.

func JSONHandler

func JSONHandler(g *Generator) fox.HandlerFunc

JSONHandler returns a Fox handler that serves the generated JSON spec.

func MarshalSpecJSON

func MarshalSpecJSON(spec *openapi3.T) ([]byte, error)

MarshalSpecJSON serializes an OpenAPI model as formatted JSON.

func MarshalSpecYAML

func MarshalSpecYAML(spec *openapi3.T) ([]byte, error)

MarshalSpecYAML serializes an OpenAPI model as YAML.

func Mount

func Mount(router Router, g *Generator, opts ...MountOption)

Mount registers YAML and JSON spec endpoints on the router.

router accepts *fox.Engine or *fox.RouterGroup. Mount forces spec generation immediately so the spec endpoints themselves are not included in the generated paths. Routes registered after Mount are not picked up unless the caller invokes Generator.Regenerate().

func YAMLHandler

func YAMLHandler(g *Generator) fox.HandlerFunc

YAMLHandler returns a Fox handler that serves the generated YAML spec.

Types

type Generator

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

Generator builds and serializes an OpenAPI specification for a Fox engine.

Generation is lazy: routes registered after New() are still picked up on the next Spec()/JSON()/YAML() call. Schemas are cached across regenerations so repeated calls only re-walk the route table.

func New

func New(engine *fox.Engine, opts ...Option) *Generator

New creates a Generator and immediately scans the engine's current routes.

func (*Generator) JSON

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

JSON serializes the generated spec as formatted JSON.

func (*Generator) Regenerate

func (g *Generator) Regenerate()

Regenerate forces a full re-scan of the engine's routes on the next access. Useful when routes are added dynamically and the caller wants the next JSON()/YAML() call to reflect them without retaining stale state.

func (*Generator) Spec

func (g *Generator) Spec() *openapi3.T

Spec returns the generated OpenAPI model. The first call walks the engine's route table; subsequent calls also re-walk so freshly registered routes are reflected.

func (*Generator) Warnings

func (g *Generator) Warnings() []string

Warnings returns non-fatal generation warnings, triggering generation if it has not yet happened.

func (*Generator) WriteYAML

func (g *Generator) WriteYAML(w io.Writer) error

WriteYAML writes the generated YAML spec to w.

func (*Generator) YAML

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

YAML serializes the generated spec as YAML.

type MountOption

type MountOption func(*mountConfig)

MountOption configures OpenAPI spec endpoint mounting.

func MountJSON

func MountJSON(path string) MountOption

MountJSON sets the JSON spec endpoint path. Empty string disables.

func MountYAML

func MountYAML(path string) MountOption

MountYAML sets the YAML spec endpoint path. Empty string disables.

type OAuthFlowConfig

type OAuthFlowConfig struct {
	AuthorizationURL string
	TokenURL         string
	RefreshURL       string
	Scopes           map[string]string
}

OAuthFlowConfig describes a serializable OAuth2 flow.

type OAuthFlowsConfig

type OAuthFlowsConfig struct {
	Implicit          *OAuthFlowConfig
	Password          *OAuthFlowConfig
	ClientCredentials *OAuthFlowConfig
	AuthorizationCode *OAuthFlowConfig
}

OAuthFlowsConfig describes serializable OAuth2 flows.

type OperationOption

type OperationOption func(*operationDoc)

OperationOption configures explicit metadata for one operation.

func Deprecated

func Deprecated(value bool) OperationOption

Deprecated marks the operation as deprecated.

func Description

func Description(value string) OperationOption

Description sets the operation description.

func OperationID

func OperationID(value string) OperationOption

OperationID sets the operationId.

func Response

func Response(status int, body any, description string) OperationOption

Response adds or replaces a response for the operation.

func Security

func Security(name string, scopes ...string) OperationOption

Security adds a security requirement to the operation.

func Summary

func Summary(value string) OperationOption

Summary sets the operation summary.

func Tags

func Tags(values ...string) OperationOption

Tags sets the operation tags.

type Option

type Option func(*Generator)

Option configures a Generator.

func Group

func Group(prefix string, opts ...OperationOption) Option

Group adds metadata to operations whose Fox route path starts with prefix.

func Info

func Info(title, version string) Option

Info sets the OpenAPI info title and version.

func Operation

func Operation(method, path string, opts ...OperationOption) Option

Operation adds explicit metadata for a registered route.

func RegisterFormatter

func RegisterFormatter(typ reflect.Type, schema *openapi3.Schema) Option

RegisterFormatter overrides schema generation for a Go type.

func SecurityScheme

func SecurityScheme(name string, scheme *openapi3.SecurityScheme) Option

SecurityScheme registers an OpenAPI security scheme.

func SecuritySchemeFromConfig

func SecuritySchemeFromConfig(name string, scheme SecuritySchemeConfig) Option

SecuritySchemeFromConfig registers a serializable OpenAPI security scheme.

func Server

func Server(url string) Option

Server appends a server URL to the generated OpenAPI spec.

func SetErrorSchema

func SetErrorSchema(body any) Option

SetErrorSchema overrides the default error response schema.

func Source

func Source(paths []string, opts ...SourceOption) Option

Source enables Go comment extraction from the provided paths. A path ending in "/..." recursively walks the tree skipping vendor and dot-prefixed directories. Test files (_test.go) are skipped unless IncludeTestFiles is passed.

type Router

type Router interface {
	GET(relativePath string, handlers ...fox.HandlerFunc) gin.IRoutes
}

Router is the minimal surface Mount needs — both *fox.Engine and *fox.RouterGroup satisfy it.

type SecuritySchemeConfig

type SecuritySchemeConfig struct {
	Type             string
	Description      string
	Name             string
	In               string
	Scheme           string
	BearerFormat     string
	OpenIDConnectURL string
	Flows            *OAuthFlowsConfig
}

SecuritySchemeConfig describes a serializable OpenAPI security scheme.

type SourceOption

type SourceOption func(*sourceConfig)

SourceOption configures Source.

func IncludeTestFiles

func IncludeTestFiles() SourceOption

IncludeTestFiles makes Source also scan _test.go files. By default test files are skipped so comments authored in tests do not bleed into production specs; this option exists for the rare case where handler documentation lives in test fixtures.

type SpecExternalDocs

type SpecExternalDocs struct {
	Description string
	URL         string
}

SpecExternalDocs describes top-level tag external documentation.

type SpecMetadata

type SpecMetadata struct {
	InfoDescription    string
	ServerDescriptions []string
	Tags               []SpecTag
}

SpecMetadata contains top-level OpenAPI metadata used by generated drivers.

type SpecTag

type SpecTag struct {
	Name         string
	Description  string
	ExternalDocs *SpecExternalDocs
}

SpecTag describes a top-level OpenAPI tag.