openapi

package
v0.99.0 Latest Latest
Warning

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

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

Documentation

Overview

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

Index

Constants

View Source 
const (
	InPath   = "path"
	InQuery  = "query"
	InHeader = "header"
	InCookie = "cookie"

	TypeString  = "string"
	TypeObject  = "object"
	TypeNull    = "null"
	TypeBoolean = "boolean"
	TypeArray   = "array"
	TypeNumber  = "number"
	TypeInteger = "integer"

	FormatInt32    = "int32"
	FormatInt64    = "int64"
	FormatFloat    = "float"
	FormatDouble   = "double"
	FormatPassword = "password"

	SecuritySchemeTypeHTTP          = "http"
	SecuritySchemeTypeAPIKey        = "apiKey"
	SecuritySchemeTypeMutualTLS     = "mutualTLS"
	SecuritySchemeTypeOAuth2        = "oauth2"
	SecuritySchemeTypeOpenIDConnect = "openIdConnect"

	// CommentTag 可提取翻译内容的结构体标签名称
	CommentTag = "comment"
)
View Source 
const Version = "3.1.0"

Version 支持的 openapi 版本

Variables

This section is empty.

Functions

This section is empty.

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 接口输出内容

func (*Document) Handler 

func (d *Document) Handler(ctx *web.Context) web.Responser

Handler 实现 web.HandlerFunc 接口

目前支持以下几种格式：

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

该路由接受 tag 查询参数，在未指定参数的情况下，表示返回所有接口， 如果指定了参数，则只返回带指定标签的接口，多个标签以逗号分隔。

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 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) *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) *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) *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) *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) PathRef 

func (o *Operation) PathRef(ref string) *Operation

func (*Operation) Query 

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

Query 指定一个查询参数

func (*Operation) QueryObject 

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

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

对于 o 的要求与 web.Context.QueryObject 是相同的。 f 是对每个字段的修改，可以为空，其原型为 

func(p *Parameter)

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

func (*Operation) QueryRef 

func (o *Operation) QueryRef(ref string) *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) ResponseRef 

func (o *Operation) ResponseRef(status string, ref string) *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, favicon 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； favicon 图标，请使用 icon 或是 png 这种大部分浏览器都支持的图标格式，可以为空；

func WithHead 

func WithHead(enable bool) Option

WithHead 是否生成 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(enable bool) Option

WithOptions 是否生成 OPTIONS 请求

func WithPath 

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

WithPath 向 components/paramters 添加 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/paramters 添加 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 的形式，如果该值不为空，那么将当前对象以此状态码应用到所有的接口；

NOTE: 多次调用会依次添加

func WithSecurityScheme 

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

WithSecurityScheme 指定验证方案

s 需要添加的验证方案； scope 如果指定了该值，那么会以 s.ID 为名称，scope 为值添加至 openapi.securiy， 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
}

func NewSchema 

func NewSchema(t reflect.Type, title, desc web.LocaleStringer) *Schema

NewSchema 根据 reflect.Type 生成 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.