openapi

package
v0.100.7 Latest Latest
Warning

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

 Go to latest Published: Dec 22, 2024 License: MIT Imports: 21 Imported by: 20

Documentation

Overview

Package openapi 采用 web.Middleware 中间件的形式生成 openapi 文档

结构体标签

  • CommentTag 用于可翻译的注释，该内容会被翻译后保存在 [Schema.Description] 中；
  • openapi 对 openapi 类型的自定义，格式为 type,format，可以自定义字段的类型和格式；

Schema

大部分情况下，通过 NewSchema 可以将一个类型直接转换为 Schema 对象， 如果对类型中的字段有特殊要求，可以通过结构体标签 openapi 进行简单的自定义： 

type State int8

type x struct {
	State State `openapi:"string"`
}

以上代码会将 State 解析为字符串类型，而不是默认的数值。

当然对于复杂的需求，还可以通过实现 OpenAPISchema 接口实现自定义： 

type State int8

func(s State) OpenAPISchema(s *Schema) {
	s.Type = TypeString
	s.Enum = []string {"stopped", "running" }
}

以上代码，会在解析 State 始终采用 OpenAPISchema 修改。

结构体标签的优先级要高于 OpenAPISchema 接口。

Index

Constants

View Source 
const (
	InPath   = "path"
	InQuery  = "query"
	InHeader = "header"
	InCookie = "cookie"
)
View Source 
const (
	TypeString  = "string"
	TypeNull    = "null"
	TypeBoolean = "boolean"
	TypeArray   = "array"
	TypeNumber  = "number"
	TypeInteger = "integer"
	TypeObject  = "object"
)
View Source 
const (
	FormatBinary   = "binary"
	FormatByte     = "byte"
	FormatInt32    = "int32"
	FormatInt64    = "int64"
	FormatFloat    = "float"
	FormatDouble   = "double"
	FormatPassword = "password"
	FormatDate     = "date"
	FormatTime     = "time"
	FormatDateTime = "date-time"
)
View Source 
const (
	SecuritySchemeTypeHTTP          = "http"
	SecuritySchemeTypeAPIKey        = "apiKey"
	SecuritySchemeTypeMutualTLS     = "mutualTLS"
	SecuritySchemeTypeOAuth2        = "oauth2"
	SecuritySchemeTypeOpenIDConnect = "openIdConnect"
)
View Source 
const CommentTag = "comment"

CommentTag 可提取翻译内容的结构体标签名称

View Source 
const EmptyResponseRef = "empty-response-ref"

文档中表示没有返回对象在 components/responses 中的引用值

View Source 
const Version = "3.1.0"

Version 支持的 openapi 版本

Variables

This section is empty.

Functions

func MarkdownProblems added in v0.99.4 

func MarkdownProblems(s web.Server, titleLevel int) web.LocaleStringer

MarkdownProblems 将 problems 的内容生成为 markdown

titleLevel 标题的级别，0-6： 如果取值为 0，表示以列表的形式输出，并忽略 detail 字段的内容。 1-6 表示输出 detail 内容，并且将 type 和 title 作为标题；

Types

type Callback 

type Callback struct {
	Ref      *Ref
	Callback map[string]*PathItem
}

type Document 

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

Document openapi 文档

func New 

func New(s web.Server, title web.LocaleStringer, o ...Option) *Document

New 声明 Document 对象

title 文档的标题；

func (*Document) API 

func (d *Document) API(f func(o *Operation)) web.Middleware

API 提供用于声明 openapi 文档的中间件

用户可通过 f 方法提供的参数 o 对接口数据进行更改。 对于 Operation 的更改，可以直接操作字段，也可以通过其提供的方法进行更改。 两者稍有区别，前者不会对数据进行验证。

func (*Document) AddWebhook 

func (d *Document) AddWebhook(name, method string, o *Operation)

AddWebhook 添加 Webhook 的定义

func (*Document) Disable 

func (d *Document) Disable(disable bool)

Disable 是否禁用 Document.Handler 接口输出内容

不影响内容的添加，但是会在调用 Document.Handler 时输出 404。

func (*Document) Handler 

func (d *Document) Handler(tag ...string) web.HandlerFunc

Handler 创建只包含给定标签的文档接口

目前支持以下几种格式：

NOTE: 支持的输出格式限定在以上几种，但是最终是否能正常输出以上几种格式， 还需要由 web.Server 是否配置相应的解码方式。

如果 tag 不为空，则表示该接口只显示与这些标签关联的文档。

func (*Document) WithDescription added in v0.100.2 

func (d *Document) WithDescription(summary, desc web.LocaleStringer)

func (*Document) WithHTML added in v0.100.2 

func (d *Document) WithHTML(tpl, assets, logo string)

func (*Document) WithSecurityScheme added in v0.100.2 

func (d *Document) WithSecurityScheme(s *SecurityScheme, scope ...[]string)

func (*Document) WithServer added in v0.100.2 

func (d *Document) WithServer(url string, desc web.LocaleStringer, vars ...*ServerVariable)

func (*Document) WithTag added in v0.100.2 

func (d *Document) WithTag(name string, desc web.LocaleStringer, extDocURL string, extDocDesc web.LocaleStringer)

WithTag 添加标签

type ExternalDocs 

type ExternalDocs struct {
	Description web.LocaleStringer
	URL         string
}

type OAuthFlow 

type OAuthFlow struct {
	AuthorizationURL string
	TokenURL         string
	RefreshURL       string
	Scopes           map[string]web.LocaleStringer
}

type OAuthFlows 

type OAuthFlows struct {
	Implicit          *OAuthFlow
	Password          *OAuthFlow
	ClientCredentials *OAuthFlow
	AuthorizationCode *OAuthFlow
}

type OpenAPISchema added in v0.100.0 

type OpenAPISchema interface {
	// OpenAPISchema 修改当前类型的 [Schema] 表示形式
	OpenAPISchema(s *Schema)
}

OpenAPISchema 自定义某个类型在 openapi 文档中的类型

type Operation 

type Operation struct {
	Summary     web.LocaleStringer
	Description web.LocaleStringer
	ID          string
	Deprecated  bool
	Tags        []string

	Paths        []*Parameter // 路径中的参数
	Queries      []*Parameter // 查询参数
	Headers      []*Parameter
	Cookies      []*Parameter
	RequestBody  *Request
	Responses    map[string]*Response // key = 状态码，比如 2XX
	Callbacks    map[string]*Callback // key = 名称
	Security     []*SecurityRequirement
	Servers      []*Server
	ExternalDocs *ExternalDocs
	// contains filtered or unexported fields
}

Operation 定义了每一个 API 的属性

func (*Operation) Body 

func (o *Operation) Body(body any, ignorable bool, desc web.LocaleStringer, f func(*Request)) *Operation

Body 从 body 参数中获取请求内容的类型

f 如果不为空，则要以对根据 body 生成的对象做二次修改。

func (*Operation) BodyRef 

func (o *Operation) BodyRef(ref string, summary, description web.LocaleStringer) *Operation

func (*Operation) Callback 

func (o *Operation) Callback(name, path, method string, f func(*Operation)) *Operation

Callback 定义回调对象

func (*Operation) CallbackRef 

func (o *Operation) CallbackRef(name, ref string, summary, description web.LocaleStringer) *Operation

CallbackRef 引用 components 中定义的回调对象

func (*Operation) Cookie 

func (o *Operation) Cookie(name, typ string, desc web.LocaleStringer, f func(*Parameter)) *Operation

Cookie 添加 Cookie

name Cookie 的名称； typ 表示该参数在 json schema 中的类型； desc 对该参数的表述； f 如果 typ 无法描述该参数的全部特征，那么可以使用 f 对该类型进行修正，否则为空；

func (*Operation) CookieRef 

func (o *Operation) CookieRef(ref string, summary, description web.LocaleStringer) *Operation

func (*Operation) Desc added in v0.99.1 

func (o *Operation) Desc(summary, description web.LocaleStringer) *Operation

func (*Operation) Header 

func (o *Operation) Header(name, typ string, desc web.LocaleStringer, f func(*Parameter)) *Operation

Header 添加报头

name 报头名称； typ 表示该参数在 json schema 中的类型； desc 对该参数的表述； f 如果 typ 无法描述该参数的全部特征，那么可以使用 f 对该类型进行修正，否则为空；

func (*Operation) HeaderRef 

func (o *Operation) HeaderRef(ref string, summary, description web.LocaleStringer) *Operation

func (*Operation) Path 

func (o *Operation) Path(name, typ string, desc web.LocaleStringer, f func(*Parameter)) *Operation

Path 指定路径参数

name 参数名称，如果参数带了类型限定，比如 /path/{id:digit} 等，需要带上类型限定符； typ 表示该参数在 json schema 中的类型； desc 对该参数的表述； f 如果 typ 无法描述该参数的全部特征，那么可以使用 f 对该类型进行修正，否则为空；

NOTE: 当同一个路径包含不同的请求方法时，只需要定义其一个请求方法中的路径参数即可， 会自动应用到所有的请求方法。

func (*Operation) PathID added in v0.99.1 

func (o *Operation) PathID(name string, desc web.LocaleStringer) *Operation

PathID 指定类型为大于 0 的路径参数

func (*Operation) PathRef 

func (o *Operation) PathRef(ref string, summary, description web.LocaleStringer) *Operation

func (*Operation) Query 

func (o *Operation) Query(name, typ string, desc web.LocaleStringer, f func(*Parameter)) *Operation

Query 指定一个查询参数

func (*Operation) QueryObject 

func (o *Operation) QueryObject(obj any, f func(*Parameter)) *Operation

QueryObject 从参数 o 中获取相应的查询参数

对于 obj 的要求与 web.Context.QueryObject 是相同的。 如果参数 obj 非空的，那么该非空字段同时也作为该查询参数的默认值。 f 是对每个字段的修改，可以为空，其原型为 

func(p *Parameter)

可通过 p.Name 确定的参数名称

func (*Operation) QueryRef 

func (o *Operation) QueryRef(ref string, summary, description web.LocaleStringer) *Operation

func (*Operation) Response 

func (o *Operation) Response(status string, resp any, desc web.LocaleStringer, f func(*Response)) *Operation

Response 从 resp 参数中获取返回对象的类型

f 如果不为空，则要以对根据 resp 生成的对象做二次修改。

func (*Operation) Response200 added in v0.100.3 

func (o *Operation) Response200(resp any) *Operation

Response200 相当于 o.Response("200", resp, nil, nil)

func (*Operation) ResponseEmpty added in v0.100.3 

func (o *Operation) ResponseEmpty(status string) *Operation

ResponseEmpty 相当于 o.ResponseRef(status, EmptyResponseRef, nil, nil)

func (*Operation) ResponseRef 

func (o *Operation) ResponseRef(status, ref string, summary, description web.LocaleStringer) *Operation

func (*Operation) Server 

func (o *Operation) Server(url string, desc web.LocaleStringer, vars ...*ServerVariable) *Operation

func (*Operation) Tag 

func (o *Operation) Tag(tag ...string) *Operation

Tag 关联指定的标签

type Option 

type Option func(*Document)

func WithCallback 

func WithCallback(c ...*Callback) Option

WithCallback 预定义回调对象

func WithContact 

func WithContact(name, email, url string) Option

WithContact 添加联系信息

NOTE: 多次调用会相互覆盖

func WithCookie 

func WithCookie(global bool, p ...*Parameter) Option

WithCookie 向 components/parameters 添加对象

p 要求必须指定 Ref.Ref。其它接口可以通过 problem 引用此对象。

global 是否将该对象默认应用在所有的接口上；

NOTE: 多次调用会依次添加

func WithDescription 

func WithDescription(summary, desc web.LocaleStringer) Option

WithDescription 指定描述信息

summary 指定的是 openapi.info.summary 属性； description 指定的是 openapi.info.description 属性；

NOTE: 多次调用会相互覆盖

func WithExternalDocs 

func WithExternalDocs(url string, desc web.LocaleStringer) Option

WithExternalDocs 指定扩展文档

NOTE: 多次调用会相互覆盖

func WithHTML 

func WithHTML(tpl, assets, logo string) Option

WithHTML 指定 HTML 模板

这将开启 Document.Handler 对 html.Mimetype 类型的支持。 此选项仅是定义了 Document.Handler 输出的一些内容， 还需要向 github.com/issue9/web/mimetype/html 添加模板。

tpl 表示 HTML 模板名称，该模板由 html.Install 注册； assets 资源基地址，apidoc 的浏览工具一般都是在一个 html 文件中引入一些依赖文件， assets 就是这些依赖文件的基地址，可是指向一个 CDN 的地址，比如 swagger 的 https://unpkg.com/swagger-ui-dist@5.18.2； logo LOGO 图标，可能还会被用于 favicon 等功能，请确保格式能被正确处理，可以为空；

NOTE: github.com/issue9/webuse/openapi 下实现了部分简单的模板。

func WithHeadMethod added in v0.99.5 

func WithHeadMethod(enable bool) Option

WithHeadMethod 是否生成 HEAD 接口请求

func WithHeader 

func WithHeader(global bool, p ...*Parameter) Option

WithHeader 向 components/headers 添加对象

p 要求必须指定 Ref.Ref，其它接口可以通过 Ref 引用该对象。 global 是否将该对象默认应用在所有的接口上；

NOTE: 多次调用会依次添加

func WithLicense 

func WithLicense(name, id string) Option

WithLicense 添加版权信息

NOTE: 多次调用会相互覆盖

func WithMediaType 

func WithMediaType(t ...string) Option

WithMediaType 指定所有接口可用的媒体类型

t 用于指定支持的媒体类型，必须是 web.Server 实例支持的类型。

NOTE: 多次调用会依次添加，相同值会合并。

func WithOptions 

func WithOptions(o ...Option) Option

WithOptions 合并多个 Option 为一个

func WithOptionsMethod added in v0.99.5 

func WithOptionsMethod(enable bool) Option

WithOptionsMethod 是否生成 OPTIONS 请求

func WithPath 

func WithPath(global bool, p ...*Parameter) Option

WithPath 向 components/parameters 添加 InPath 的对象

p 要求必须指定 Ref.Ref。其它接口可以通过 ref 引用此对象。

NOTE: 多次调用会依次添加

func WithProblemResponse 

func WithProblemResponse() Option

PresetOptions 提供 web.Problem 的 Response 对象并应用所有接口的 4XX 和 5XX 状态码

func WithQuery 

func WithQuery(p ...*Parameter) Option

WithQuery 向 components/parameters 添加 InQuery 的对象

p 要求必须指定 Ref.Ref。其它接口可以通过 ref 引用此对象。

NOTE: 多次调用会依次添加

func WithResponse 

func WithResponse(resp *Response, status ...string) Option

WithResponse 向 components/responses 添加对象

一般用于指定非正常状态的返回对象，比如 400 状态码的对象。

resp 返回对象，需要指定 resp.Ref.Ref，其它接口可以通过 Ref 引用该对象； status: 状态码，可以是 4XX 的形式，如果该值不为空，那么将当前对象以此状态码应用到所有的接口， 否则仅仅是写入 components/responses，后续需要用户手动引用；

NOTE: 多次调用会依次添加

func WithSecurityScheme 

func WithSecurityScheme(s *SecurityScheme, scope ...[]string) Option

WithSecurityScheme 指定验证方案

s 需要添加的验证方案； scope 如果指定了该值，那么会以 s.ID 为名称，scope 为值添加至 openapi.security， scope 如果是多个参数，每个参数应该都是不同的；

NOTE: 多次调用会依次添加

func WithServer 

func WithServer(url string, desc web.LocaleStringer, vars ...*ServerVariable) Option

WithServer 添加 openapi.servers 变量

func WithTag 

func WithTag(name string, desc web.LocaleStringer, extDocURL string, extDocDesc web.LocaleStringer) Option

WithTag 添加标签

name 标签名称； desc 标签描述； extDocURL 扩展文档的地址； extDocDesc 扩展文档的描述；

NOTE: 多次调用会依次添加

func WithTerms 

func WithTerms(url string) Option

WithTerms 服务条款的连接

NOTE: 多次调用会相互覆盖

type Parameter 

type Parameter struct {
	Ref *Ref

	Name        string
	Deprecated  bool
	Required    bool
	Description web.LocaleStringer // 当前参数的描述信息

	// InHeader 模式下此值无效
	Schema *Schema
}

type PathItem 

type PathItem struct {
	Ref        *Ref
	Operations map[string]*Operation
	Servers    []*Server

	Paths   []*Parameter // 路径中的参数
	Queries []*Parameter // 查询参数
	Headers []*Parameter
	Cookies []*Parameter
}

type Ref 

type Ref struct {
	Ref         string
	Summary     web.LocaleStringer
	Description web.LocaleStringer
}

Ref 定义了 $ref

type Request 

type Request struct {
	Ref         *Ref
	Ignorable   bool // 对应 requestBody.required
	Description web.LocaleStringer

	// Body 和 Content 共同组成了正文内容
	// 所有不在 Content 中出现的类型均采用 [Document.MediaTypes] 与 Body 相结合。
	Body    *Schema
	Content map[string]*Schema // key = mimetype
}

type Response 

type Response struct {
	Ref         *Ref
	Headers     []*Parameter
	Description web.LocaleStringer

	// 是否是用于表示错误类型的
	//
	// 该值如果为 true，会尝试在查找对应的媒体类型，
	// 比如在 [web.Server] 将 application/json 对应为 application/problem+json，
	// 那么在当前对象输出时，也会将媒体类型转换为 application/problem+json。
	Problem bool

	// Body 和 Content 共同组成了正文内容
	// 所有不在 Content 中出现的类型均采用 [openAPI.MediaTypesRenderer] 与 Body 相结合。
	Body    *Schema
	Content map[string]*Schema // key = mimetype
}

type Schema 

type Schema struct {
	Ref *Ref

	XML                  *XML
	ExternalDocs         *ExternalDocs
	Title                web.LocaleStringer
	Description          web.LocaleStringer
	Type                 string
	AllOf                []*Schema
	OneOf                []*Schema
	AnyOf                []*Schema
	Format               string
	Items                *Schema
	Properties           map[string]*Schema
	AdditionalProperties *Schema
	Required             []string
	Minimum              int
	Maximum              int
	Enum                 []any
	Default              any
}

func AllOfSchema added in v0.99.4 

func AllOfSchema(title, desc web.LocaleStringer, v ...any) *Schema

func AnyOfSchema added in v0.99.4 

func AnyOfSchema(title, desc web.LocaleStringer, v ...any) *Schema

func NewSchema 

func NewSchema(v any, title, desc web.LocaleStringer) *Schema

NewSchema 根据 v 生成 Schema 对象

如果 v 不是空值，那么 v 也将同时作为默认值出现在 Schema 中。

func OneOfSchema added in v0.99.4 

func OneOfSchema(title, desc web.LocaleStringer, v ...any) *Schema

type SecurityRequirement 

type SecurityRequirement struct {
	Name   string
	Scopes []string
}

type SecurityScheme 

type SecurityScheme struct {
	ID string // 在 components 中的键名，要求唯一性。

	Type             string
	Description      web.LocaleStringer
	Name             string
	In               string
	Scheme           string
	BearerFormat     string
	Flows            *OAuthFlows
	OpenIDConnectURL string
}

type Server 

type Server struct {
	URL         string
	Description web.LocaleStringer
	Variables   []*ServerVariable
}

type ServerVariable 

type ServerVariable struct {
	Name        string
	Default     string
	Description web.LocaleStringer
	Enums       []string
}

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"`
	Wrapped   bool   `json:"wrapped,omitempty" yaml:"wrapped,omitempty"`
	Attribute bool   `json:"attribute,omitempty" yaml:"attribute,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.