openapi

Documentation

Overview

Package openapi provides the schema and registry types used to build OpenAPI documents for typed server routes.

Index

• func ApplyFieldSchemaMetadata(schema *Schema, f reflect.StructField)
• type Components
• type Contact
• type Info
• type License
• type MediaType
• type OAuthFlow
• type OAuthFlows
• type OpenAPI
  • func NewOpenAPI(title, version string) *OpenAPI
  • func (o *OpenAPI) AddOperation(method, path string, op *Operation)
  • func (o *OpenAPI) AddSchema(name string, schema *Schema)
  • func (o *OpenAPI) AddSecurityScheme(name string, scheme *SecurityScheme)
• type Operation
• type Parameter
• type PathItem
• type Registry
  • func NewRegistry(prefix string) *Registry
  • func (r *Registry) MarshalJSON() ([]byte, error)
  • func (r *Registry) Schema(t reflect.Type) *Schema
  • func (r *Registry) SchemaUnlocked(t reflect.Type) *Schema
  • func (r *Registry) Schemas() map[reflect.Type]*Schema
• type RequestBody
• type Response
• type Schema
  • func CloneSchema(s *Schema) *Schema
• type SchemaProvider
• type SchemaRegistry
  • func Register[T any](r *Registry) *SchemaRegistry[T]
  • func (s *SchemaRegistry[T]) Ref() string
  • func (s *SchemaRegistry[T]) Schema() *Schema
• type SecurityScheme
• type Server
• type ServerVariable

Functions

func ApplyFieldSchemaMetadata

func ApplyFieldSchemaMetadata(schema *Schema, f reflect.StructField)

Types

type Components

type Components struct {
	Schemas         map[string]*Schema         `json:"schemas,omitempty"`
	Parameters      map[string]*Parameter      `json:"parameters,omitempty"`
	Responses       map[string]*Response       `json:"responses,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty"`
}

type Contact

type Contact struct {
	Name  string `json:"name,omitempty"`
	URL   string `json:"url,omitempty"`
	Email string `json:"email,omitempty"`
}

type Info

type Info struct {
	Contact     *Contact `json:"contact,omitempty"`
	License     *License `json:"license,omitempty"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Version     string   `json:"version"`
}

type License

type License struct {
	Name       string `json:"name,omitempty"`
	Identifier string `json:"identifier,omitempty"`
	URL        string `json:"url,omitempty"`
}

type MediaType

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

type OAuthFlow

type OAuthFlow struct {
	Scopes           map[string]string `json:"scopes,omitempty"`
	AuthorizationURL string            `json:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty"`
	RefreshURL       string            `json:"refreshUrl,omitempty"`
}

OAuthFlow describes a single OAuth2 flow.

type OAuthFlows

type OAuthFlows struct {
	Implicit          *OAuthFlow `json:"implicit,omitempty"`
	Password          *OAuthFlow `json:"password,omitempty"`
	ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty"`
}

OAuthFlows describes the OAuth2 flows for an oauth2 SecurityScheme.

type OpenAPI

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

func NewOpenAPI

func NewOpenAPI(title, version string) *OpenAPI

func (*OpenAPI) AddOperation

func (o *OpenAPI) AddOperation(method, path string, op *Operation)

func (*OpenAPI) AddSchema

func (o *OpenAPI) AddSchema(name string, schema *Schema)

func (*OpenAPI) AddSecurityScheme

func (o *OpenAPI) AddSecurityScheme(name string, scheme *SecurityScheme)

AddSecurityScheme registers a named security scheme under components.securitySchemes. The name is what operations reference in their security requirements.

type Operation

type Operation struct {
	RequestBody *RequestBody          `json:"requestBody,omitempty"`
	Responses   map[string]*Response  `json:"responses,omitempty"`
	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"`
	Security    []map[string][]string `json:"security,omitempty"`
	Deprecated  bool                  `json:"deprecated,omitempty"`
}

type Parameter

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

type PathItem

type PathItem struct {
	Ref        string       `json:"$ref,omitempty"`
	GET        *Operation   `json:"get,omitempty"`
	PUT        *Operation   `json:"put,omitempty"`
	POST       *Operation   `json:"post,omitempty"`
	DELETE     *Operation   `json:"delete,omitempty"`
	OPTIONS    *Operation   `json:"options,omitempty"`
	HEAD       *Operation   `json:"head,omitempty"`
	PATCH      *Operation   `json:"patch,omitempty"`
	TRACE      *Operation   `json:"trace,omitempty"`
	CONNECT    *Operation   `json:"connect,omitempty"`
	Parameters []*Parameter `json:"parameters,omitempty"`
}

type Registry

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

func NewRegistry

func NewRegistry(prefix string) *Registry

func (*Registry) MarshalJSON

func (r *Registry) MarshalJSON() ([]byte, error)

func (*Registry) Schema

func (r *Registry) Schema(t reflect.Type) *Schema

func (*Registry) SchemaUnlocked

func (r *Registry) SchemaUnlocked(t reflect.Type) *Schema

func (*Registry) Schemas

func (r *Registry) Schemas() map[reflect.Type]*Schema

type RequestBody

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

type Response

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

type Schema

type Schema struct {
	Default              any                `json:"default,omitempty"`
	AdditionalProperties any                `json:"additionalProperties,omitempty"`
	Example              any                `json:"example,omitempty"`
	Not                  *Schema            `json:"not,omitempty"`
	MaxItems             *int               `json:"maxItems,omitempty"`
	MaxProperties        *int               `json:"maxProperties,omitempty"`
	MinProperties        *int               `json:"minProperties,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	ExclusiveMinimum     *float64           `json:"exclusiveMinimum,omitempty"`
	MinItems             *int               `json:"minItems,omitempty"`
	Maximum              *float64           `json:"maximum,omitempty"`
	MinLength            *int               `json:"minLength,omitempty"`
	ExclusiveMaximum     *float64           `json:"exclusiveMaximum,omitempty"`
	Minimum              *float64           `json:"minimum,omitempty"`
	MaxLength            *int               `json:"maxLength,omitempty"`
	Description          string             `json:"description,omitempty"`
	Title                string             `json:"title,omitempty"`
	Type                 string             `json:"type,omitempty"`
	Format               string             `json:"format,omitempty"`
	Pattern              string             `json:"pattern,omitempty"`
	Ref                  string             `json:"$ref,omitempty"`
	AllOf                []*Schema          `json:"allOf,omitempty"`
	Enum                 []any              `json:"enum,omitempty"`
	OneOf                []*Schema          `json:"oneOf,omitempty"`
	AnyOf                []*Schema          `json:"anyOf,omitempty"`
	Required             []string           `json:"required,omitempty"`
	UniqueItems          bool               `json:"uniqueItems,omitempty"`
	Nullable             bool               `json:"nullable,omitempty"`
	ReadOnly             bool               `json:"readOnly,omitempty"`
	WriteOnly            bool               `json:"writeOnly,omitempty"`
	Deprecated           bool               `json:"deprecated,omitempty"`
}

func CloneSchema

func CloneSchema(s *Schema) *Schema

type SchemaProvider

type SchemaProvider interface {
	Schema() *Schema
}

type SchemaRegistry

type SchemaRegistry[T any] struct {
	// contains filtered or unexported fields
}

func Register

func Register[T any](r *Registry) *SchemaRegistry[T]

func (*SchemaRegistry[T]) Ref

func (s *SchemaRegistry[T]) Ref() string

func (*SchemaRegistry[T]) Schema

func (s *SchemaRegistry[T]) Schema() *Schema

type SecurityScheme

type SecurityScheme struct {
	// Type is one of "apiKey", "http", "mutualTLS", "oauth2", or
	// "openIdConnect".
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
	// Name and In apply to type "apiKey" (In is "query", "header", or
	// "cookie").
	Name string `json:"name,omitempty"`
	In   string `json:"in,omitempty"`
	// Scheme and BearerFormat apply to type "http" (e.g. "bearer", "basic").
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
	// Flows applies to type "oauth2".
	Flows *OAuthFlows `json:"flows,omitempty"`
	// OpenIDConnectURL applies to type "openIdConnect".
	OpenIDConnectURL string `json:"openIdConnectUrl,omitempty"`
}

SecurityScheme describes a single OpenAPI security scheme (an authentication method). See https://spec.openapis.org/oas/v3.1.0#security-scheme-object.

type Server

type Server struct {
	Variables   map[string]*ServerVariable `json:"variables,omitempty"`
	URL         string                     `json:"url"`
	Description string                     `json:"description,omitempty"`
}

type ServerVariable

type ServerVariable struct {
	Default     string   `json:"default"`
	Description string   `json:"description,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}