openapi

package
v2.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 23, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Generate

func Generate(outputPath string, title string, version string, routes []RouteInfo, securitySchemes map[string]SecurityScheme) error

func RegisterDocsRoutes

func RegisterDocsRoutes(r *router.Router, openAPIFilePath string)

Types

type Components

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

Components holds reusable OpenAPI components.

type Document

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

type Info

type Info struct {
	Title   string `json:"title"`
	Version string `json:"version"`
}

type MediaType

type MediaType struct {
	Schema Schema `json:"schema"`
	// Example 是该 media type 的完整示例值(整个 body), 优先级高于各字段自己的 example.
	Example any `json:"example,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]ResponseEntry `json:"responses"`
	Security    []SecurityRequirement    `json:"security,omitempty"`
}

type Parameter

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

type PathItem

type PathItem map[string]Operation

type RequestBody

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

type ResponseEntry

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

type RouteInfo

type RouteInfo struct {
	Method               string
	Path                 string
	OperationID          string
	OperationDescription string
	TagName              string
	TagDescription       string
	Parameters           []Parameter
	RequestBody          *RequestBody
	ResponseSchema       *Schema
	// ResponseExample 是响应的完整示例值(整个 body). 留空时 openapi 层用
	// ResponseSchema 自带的 Example 兜底.
	ResponseExample any
	Security        []SecurityRequirement
}

type Schema

type Schema struct {
	Type                 string            `json:"type,omitempty"`
	Format               string            `json:"format,omitempty"`
	Description          string            `json:"description,omitempty"`
	Required             []string          `json:"required,omitempty"`
	Enum                 []any             `json:"enum,omitempty"`
	Properties           map[string]Schema `json:"properties,omitempty"`
	Items                *Schema           `json:"items,omitempty"`
	AdditionalProperties *Schema           `json:"additionalProperties,omitempty"`
	// Default 是该字段的默认值. 优先取 model 字段上 default tag 的显式标注,
	// 未标注时按类型给出零值(string -> "", 数值 -> 0, bool -> false).
	Default any `json:"default,omitempty"`
	// Example 是该字段的示例值. 优先取 model 字段上 example tag 的显式标注,
	// 未标注时按类型给出占位示例(string -> "string", 整数 -> 1, 浮点 -> 1.5, bool -> true).
	Example any `json:"example,omitempty"`
}

type SecurityRequirement

type SecurityRequirement map[string][]string

SecurityRequirement maps a security scheme name to its scopes (empty for most cases).

type SecurityScheme

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

SecurityScheme represents an OpenAPI security scheme definition.

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