openapi

package
v3.13.0 Latest Latest
Warning

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

Go to latest
Published: Jul 24, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package openapi provides OpenAPI 3.0.3 document generation from routes and Go types.

Index

Constants

View Source
const ServiceOpenApiInfo = "service.openapi.info"
View Source
const ServiceOpenApiRegistry = "service.openapi.registry"

Variables

This section is empty.

Functions

func SpecHandler

func SpecHandler(info Info, registry *Registry) httpcontract.Handler

func TypeOf

func TypeOf[T any]() reflect.Type

Types

type Components

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

type DescribeOption

type DescribeOption func(*Descriptor)

func WithDescription

func WithDescription(description string) DescribeOption

func WithResponse

func WithResponse[T any](status int) DescribeOption

func WithSummary

func WithSummary(summary string) DescribeOption

func WithTags

func WithTags(tags ...string) DescribeOption

type Descriptor

type Descriptor struct {
	Summary     string
	Description string
	Tags        []string
	RequestType reflect.Type
	Responses   map[int]reflect.Type
}

type Document

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

func Generate

func Generate(
	info Info,
	routeDefinitions []httpcontract.RouteDefinition,
	registry *Registry,
) *Document

type ExternalDocs

type ExternalDocs struct {
	Url         string `json:"url"`
	Description string `json:"description,omitempty"`
}

type GenerateCommand

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

func NewGenerateCommand

func NewGenerateCommand(info Info, registry *Registry) *GenerateCommand

func NewGenerateCommandFromContainer added in v3.9.0

func NewGenerateCommandFromContainer() *GenerateCommand

NewGenerateCommandFromContainer builds the command so it resolves its Info and Registry from the service container at run time, letting the framework auto-register it without the application wiring those dependencies by hand.

func (*GenerateCommand) Description

func (instance *GenerateCommand) Description() string

func (*GenerateCommand) Flags

func (instance *GenerateCommand) Flags() []clicontract.Flag

func (*GenerateCommand) Name

func (instance *GenerateCommand) Name() string

func (*GenerateCommand) Run

func (instance *GenerateCommand) Run(
	runtimeInstance runtimecontract.Runtime,
	commandContext *clicontract.CommandContext,
) error

type Info

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

func InfoFromResolver added in v3.9.0

func InfoFromResolver(resolver containercontract.Resolver) Info

InfoFromResolver returns the document Info registered by the application, or an empty Info when none was registered (the Info is optional metadata, not a hard dependency).

type MediaType

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

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

type Parameter

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

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"`
	Options *Operation `json:"options,omitempty"`
	Head    *Operation `json:"head,omitempty"`
	Trace   *Operation `json:"trace,omitempty"`
}

type Registry

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

func DescribeTyped

func DescribeTyped[Req any, Resp any](registry *Registry, routeName string, status int, options ...DescribeOption) *Registry

func NewRegistry

func NewRegistry() *Registry

func RegistryMustFromContainer

func RegistryMustFromContainer(serviceContainer containercontract.Container) *Registry

func RegistryMustFromResolver

func RegistryMustFromResolver(resolver containercontract.Resolver) *Registry

func (*Registry) Describe

func (instance *Registry) Describe(routeName string, descriptor Descriptor) *Registry

func (*Registry) Get

func (instance *Registry) Get(routeName string) (Descriptor, bool)

type RequestBody

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

type ResponseObject

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

type Schema

type Schema struct {
	Ref                  string             `json:"$ref,omitempty"`
	AllOf                []*Schema          `json:"allOf,omitempty"`
	Type                 string             `json:"type,omitempty"`
	Format               string             `json:"format,omitempty"`
	Description          string             `json:"description,omitempty"`
	Nullable             bool               `json:"nullable,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
	MinLength            *int               `json:"minLength,omitempty"`
	MaxLength            *int               `json:"maxLength,omitempty"`
	MinItems             *int               `json:"minItems,omitempty"`
	MaxItems             *int               `json:"maxItems,omitempty"`
	MinProperties        *int               `json:"minProperties,omitempty"`
	MaxProperties        *int               `json:"maxProperties,omitempty"`
	Minimum              *float64           `json:"minimum,omitempty"`
	Maximum              *float64           `json:"maximum,omitempty"`
	ExclusiveMinimum     *bool              `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     *bool              `json:"exclusiveMaximum,omitempty"`
	Pattern              string             `json:"pattern,omitempty"`
	Enum                 *[]any             `json:"enum,omitempty"`
	Not                  *Schema            `json:"not,omitempty"`
}

type Server

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

type Tag

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL