openapi

Documentation

Index

• Variables
• func Handler(doc *Document) http.Handler
• type Builder
  • func New(info Info) *Builder
  • func (b *Builder) AddRoute(method, path string, op Operation) error
  • func (b *Builder) AddSchema(name string, schema Schema)
  • func (b *Builder) AddSecurityScheme(name string, scheme SecurityScheme)
  • func (b *Builder) AddServer(server Server)
  • func (b *Builder) AddTag(tag Tag)
  • func (b *Builder) Document() *Document
  • func (b *Builder) Handler() http.Handler
• type Components
• type Document
• type Header
• type Info
• type MediaType
• type Operation
• type Parameter
• type PathItem
• type RequestBody
• type Response
• type Schema
• type SecurityScheme
• type Server
• type Tag

Variables

var ErrUnsupportedMethod = errors.New("unsupported method")

ErrUnsupportedMethod is returned for unsupported HTTP methods.

Functions

func Handler

func Handler(doc *Document) http.Handler

Handler returns an HTTP handler that serves the document as JSON.

Types

type Builder

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

Builder helps compose a Document.

func New

func New(info Info) *Builder

New creates a Builder with default OpenAPI version.

func (*Builder) AddRoute

func (b *Builder) AddRoute(method, path string, op Operation) error

AddRoute adds an operation for a method/path.

func (*Builder) AddSchema

func (b *Builder) AddSchema(name string, schema Schema)

AddSchema registers a schema in components.

func (*Builder) AddSecurityScheme

func (b *Builder) AddSecurityScheme(name string, scheme SecurityScheme)

AddSecurityScheme registers a security scheme in components.

func (*Builder) AddServer

func (b *Builder) AddServer(server Server)

AddServer registers a server entry.

func (*Builder) AddTag

func (b *Builder) AddTag(tag Tag)

AddTag registers a tag.

func (*Builder) Document

func (b *Builder) Document() *Document

Document returns the built document.

func (*Builder) Handler

func (b *Builder) Handler() http.Handler

Handler returns an HTTP handler that serves the builder document as JSON.

type Components

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

Components holds reusable schemas and security schemes.

type Document

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

Document describes an OpenAPI document.

type Header

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

Header describes a response header.

type Info

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

Info describes API metadata.

type MediaType

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

MediaType describes content.

type Operation

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

Operation describes a single API operation.

type Parameter

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

Parameter describes an operation parameter.

type PathItem

type PathItem struct {
	Get     *Operation `json:"get,omitempty"`
	Post    *Operation `json:"post,omitempty"`
	Put     *Operation `json:"put,omitempty"`
	Patch   *Operation `json:"patch,omitempty"`
	Delete  *Operation `json:"delete,omitempty"`
	Head    *Operation `json:"head,omitempty"`
	Options *Operation `json:"options,omitempty"`
	Trace   *Operation `json:"trace,omitempty"`
}

PathItem describes available operations on a path.

type RequestBody

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

RequestBody describes a request payload.

type Response

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

Response describes a response.

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"`
	Required    []string          `json:"required,omitempty"`
	Enum        []string          `json:"enum,omitempty"`
}

Schema describes a data schema.

type SecurityScheme

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

SecurityScheme describes auth schemes.

type Server

type Server struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

Server describes a server entry.

type Tag

type Tag struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

Tag describes a tag for grouping operations.