swagger

Documentation

Index

• Constants
• type AllOf
  • func MakeAllOf(attributes AllOfAttributes) AllOf
• type AllOfAttributes
• type AllOfFields
• type Components
• type Contact
• type Example
• type ExternalDocs
• type FactoryStructToSchema
  • func NewFactoryStructToSchema() *FactoryStructToSchema
  • func (f *FactoryStructToSchema) Components() *Components
  • func (f *FactoryStructToSchema) MakeSchema(media docs.MediaType, root any) (*Schema, error)
• type Header
• type Info
• type License
• type Link
• type MediaType
• type OpenAPI3
• type OpenAPI3Viewer
  • func NewViewer() *OpenAPI3Viewer
  • func (v *OpenAPI3Viewer) Handlers() []docs.DocViewerHandler
  • func (v *OpenAPI3Viewer) Load(options OpenAPI3ViewerOptions) docs.IDocViewer
  • func (v *OpenAPI3Viewer) Logger(logger log.Log) docs.IDocViewer
  • func (v *OpenAPI3Viewer) RegisterGroup(group string, data docs.DocGroup) docs.IDocViewer
  • func (v *OpenAPI3Viewer) RegisterRoute(route docs.DocOperation) docs.IDocViewer
• type OpenAPI3ViewerOptions
• type Operation
• type Parameter
• type PathItem
• type RequestBody
• type Response
• type Schema
  • func NewSchema() *Schema
• type SecurityScheme
• type Server
• type ServerVariable
• type Tag
• type XML

Constants

const SWAGGER string = "SWAGGER"

const SWAGGER_JSON = "/swagger/doc.json"

const SWAGGER_ROUTE = "/swagger/"

Types

type AllOf

type AllOf []AllOfAttributes

func MakeAllOf

func MakeAllOf(attributes AllOfAttributes) AllOf

type AllOfAttributes

type AllOfAttributes map[AllOfFields]any

type AllOfFields

type AllOfFields string

const (
	ALL_OF_REF AllOfFields = "$ref"
)

type Components

type Components struct {
	Schemas         map[string]Schema         `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	Responses       map[string]Response       `json:"responses,omitempty" yaml:"responses,omitempty"`
	Parameters      map[string]Parameter      `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Examples        map[string]Example        `json:"examples,omitempty" yaml:"examples,omitempty"`
	RequestBodies   map[string]Parameter      `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
	Headers         map[string]Header         `json:"headers,omitempty" yaml:"headers,omitempty"`
	Links           map[string]Link           `json:"links,omitempty" yaml:"links,omitempty"`
	SecuritySchemes map[string]SecurityScheme `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
}

type Contact

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

type Example

type Example struct {
	Ref           string      `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Summary       string      `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description   string      `json:"description,omitempty" yaml:"description,omitempty"`
	Value         interface{} `json:"value,omitempty" yaml:"value,omitempty"`
	ExternalValue string      `json:"externalValue,omitempty" yaml:"externalValue,omitempty"`
}

type ExternalDocs

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

type FactoryStructToSchema

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

FactoryStructToSchema builds OpenAPI 3.0 schema definitions from Go structs. It uses reflection to walk struct fields, inspect tags, and generate JSON/XML schemas.

func NewFactoryStructToSchema

func NewFactoryStructToSchema() *FactoryStructToSchema

NewFactoryStructToSchema creates a new factory instance.

func (*FactoryStructToSchema) Components

func (f *FactoryStructToSchema) Components() *Components

Components returns all schemas collected so far as OpenAPI components.

func (*FactoryStructToSchema) MakeSchema

func (f *FactoryStructToSchema) MakeSchema(media docs.MediaType, root any) (*Schema, error)

MakeSchema creates a schema reference for a given payload. - If the payload is a struct, it will be added to the components. - If the payload is a slice/array, it wraps the item schema in an "array" type.

type Header

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

type Info

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

type License

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

type Link

type Link struct {
	Ref         string                 `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	OperationID string                 `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Description string                 `json:"description,omitempty" yaml:"description,omitempty"`
	Parameters  map[string]interface{} `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

type MediaType

type MediaType struct {
	Schema   *Schema            `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example  interface{}        `json:"example,omitempty" yaml:"example,omitempty"`
	Examples map[string]Example `json:"examples,omitempty" yaml:"examples,omitempty"`
}

type OpenAPI3

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

type OpenAPI3Viewer

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

OpenAPI3Viewer implements the docs.IDocViewer interface and exposes API documentation in OpenAPI 3.0 format.

func NewViewer

func NewViewer() *OpenAPI3Viewer

NewViewer creates a new OpenAPI3Viewer with default values.

func (*OpenAPI3Viewer) Handlers

func (v *OpenAPI3Viewer) Handlers() []docs.DocViewerHandler

Handlers returns the HTTP handlers for the Swagger UI and JSON definition.

Routes:

• GET /swagger/ → Swagger UI
• GET /swagger/doc.json → OpenAPI 3 JSON document

func (*OpenAPI3Viewer) Load

func (v *OpenAPI3Viewer) Load(options OpenAPI3ViewerOptions) docs.IDocViewer

Load loads the OpenAPI 3 specification from a YAML file, and configures server URLs based on the provided options.

It automatically registers `http://localhost:{Port}` if OnlyTLS is false, and `https://localhost:{PortTLS}` if EnableTLS is true.

func (*OpenAPI3Viewer) Logger

func (v *OpenAPI3Viewer) Logger(logger log.Log) docs.IDocViewer

Logger sets the logger for the viewer and returns itself.

func (*OpenAPI3Viewer) RegisterGroup

func (v *OpenAPI3Viewer) RegisterGroup(group string, data docs.DocGroup) docs.IDocViewer

RegisterGroup registers shared documentation (headers, cookies, responses) for a group of routes identified by a prefix.

func (*OpenAPI3Viewer) RegisterRoute

func (v *OpenAPI3Viewer) RegisterRoute(route docs.DocOperation) docs.IDocViewer

RegisterRoute registers an individual route operation into the OpenAPI 3 definition.

It maps the route’s method, path, parameters, request, and responses into the corresponding OpenAPI structures.

type OpenAPI3ViewerOptions

type OpenAPI3ViewerOptions struct {
	Version   string // API version
	EnableTLS bool   // Whether to expose an HTTPS server URL
	OnlyTLS   bool   // Whether to expose only HTTPS server URL
	Port      int    // HTTP port
	PortTLS   int    // HTTPS port
	FileYML   string // Path to an existing OpenAPI YAML file to preload
}

OpenAPI3ViewerOptions defines the configuration for the OpenAPI 3.0 viewer.

type Operation

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

type Parameter

type Parameter struct {
	Ref         string  `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Name        string  `json:"name" yaml:"name"`
	In          string  `json:"in" yaml:"in"`
	Description string  `json:"description,omitempty" yaml:"description,omitempty"`
	Required    bool    `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated  bool    `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmpty  bool    `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Schema      *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
}

type PathItem

type PathItem struct {
	Summary     string      `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Get         *Operation  `json:"get,omitempty" yaml:"get,omitempty"`
	Put         *Operation  `json:"put,omitempty" yaml:"put,omitempty"`
	Post        *Operation  `json:"post,omitempty" yaml:"post,omitempty"`
	Delete      *Operation  `json:"delete,omitempty" yaml:"delete,omitempty"`
	Options     *Operation  `json:"options,omitempty" yaml:"options,omitempty"`
	Head        *Operation  `json:"head,omitempty" yaml:"head,omitempty"`
	Patch       *Operation  `json:"patch,omitempty" yaml:"patch,omitempty"`
	Trace       *Operation  `json:"trace,omitempty" yaml:"trace,omitempty"`
	Servers     []Server    `json:"servers,omitempty" yaml:"servers,omitempty"`
	Parameters  []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

type RequestBody

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

type Response

type Response struct {
	Ref         string               `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Description string               `json:"description" yaml:"description"`
	Headers     map[string]Header    `json:"headers,omitempty" yaml:"headers,omitempty"`
	Content     map[string]MediaType `json:"content,omitempty" yaml:"content,omitempty"`
	Links       map[string]Link      `json:"links,omitempty" yaml:"links,omitempty"`
}

type Schema

type Schema struct {
	Ref                  string             `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Title                string             `json:"title,omitempty" yaml:"title,omitempty"`
	Type                 string             `json:"type,omitempty" yaml:"type,omitempty"`
	Format               string             `json:"format,omitempty" yaml:"format,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
	Items                *Schema            `json:"items,omitempty" yaml:"items,omitempty"`
	Required             []string           `json:"required,omitempty" yaml:"required,omitempty"`
	Enum                 []interface{}      `json:"enum,omitempty" yaml:"enum,omitempty"`
	Description          string             `json:"description,omitempty" yaml:"description,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	AllOf                AllOf              `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	XML                  *XML               `json:"xml,omitempty" yaml:"xml,omitempty"`
}

func NewSchema

func NewSchema() *Schema

type SecurityScheme

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

type Server

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

type ServerVariable

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

type Tag

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

type XML

type XML struct {
	Name      string `json:"name,omitempty" yaml:"name,omitempty"`
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Prefix    string `json:"prefix,omitempty" yaml:"prefix,omitempty"`
	Attribute bool   `json:"attribute,omitempty" yaml:"attribute,omitempty"`
	Wrapped   bool   `json:"wrapped,omitempty" yaml:"wrapped,omitempty"`
}