goai
原文：https://pkg.go.dev/github.com/gogf/gf/v2@v2.6.4/net/goai
Package goai implements and provides document generating for OpenApi specification.
软件包 goai 实现并提供 OpenApi 规范的文档生成。
https://editor.swagger.io/
常量
View Source
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| const (
TypeInteger = `integer`
TypeNumber = `number`
TypeBoolean = `boolean`
TypeArray = `array`
TypeString = `string`
TypeFile = `file`
TypeObject = `object`
FormatInt32 = `int32`
FormatInt64 = `int64`
FormatDouble = `double`
FormatByte = `byte`
FormatBinary = `binary`
FormatDate = `date`
FormatDateTime = `date-time`
FormatPassword = `password`
)
|
View Source
1
2
3
4
5
6
| const (
ParameterInHeader = `header`
ParameterInPath = `path`
ParameterInQuery = `query`
ParameterInCookie = `cookie`
)
|
变量
This section is empty.
函数
This section is empty.
类型
1
2
3
4
5
6
| type AddInput struct {
Path string // Path specifies the custom path if this is not configured in Meta of struct tag.
Prefix string // Prefix specifies the custom route path prefix, which will be added with the path tag in Meta of struct tag.
Method string // Method specifies the custom HTTP method if this is not configured in Meta of struct tag.
Object interface{} // Object can be an instance of struct or a route function.
}
|
AddInput is the structured parameter for function OpenApiV3.Add.
AddInput 是函数 OpenApiV3.Add 的结构化参数。
type Callback
1
| type Callback map[string]*Path
|
Callback is specified by OpenAPI/Swagger standard version 3.0.
回调由 OpenAPI/Swagger 标准版本 3.0 指定。
type CallbackRef
1
2
3
4
| type CallbackRef struct {
Ref string
Value *Callback
}
|
(CallbackRef) MarshalJSON
1
| func (r CallbackRef) MarshalJSON() ([]byte, error)
|
type Callbacks
1
| type Callbacks map[string]*CallbackRef
|
type Components
1
2
3
4
5
6
7
8
9
10
11
| type Components struct {
Schemas Schemas `json:"schemas,omitempty"`
Parameters ParametersMap `json:"parameters,omitempty"`
Headers Headers `json:"headers,omitempty"`
RequestBodies RequestBodies `json:"requestBodies,omitempty"`
Responses Responses `json:"responses,omitempty"`
SecuritySchemes SecuritySchemes `json:"securitySchemes,omitempty"`
Examples Examples `json:"examples,omitempty"`
Links Links `json:"links,omitempty"`
Callbacks Callbacks `json:"callbacks,omitempty"`
}
|
Components is specified by OpenAPI/Swagger standard version 3.0.
组件由 OpenAPI/Swagger 标准版本 3.0 指定。
type Config
1
2
3
4
5
6
7
8
9
| type Config struct {
ReadContentTypes []string // ReadContentTypes specifies the default MIME types for consuming if MIME types are not configured.
WriteContentTypes []string // WriteContentTypes specifies the default MIME types for producing if MIME types are not configured.
CommonRequest interface{} // Common request structure for all paths.
CommonRequestDataField string // Common request field name to be replaced with certain business request structure. Eg: `Data`, `Request.`.
CommonResponse interface{} // Common response structure for all paths.
CommonResponseDataField string // Common response field name to be replaced with certain business response structure. Eg: `Data`, `Response.`.
IgnorePkgPath bool // Ignores package name for schema name.
}
|
Config provides extra configuration feature for OpenApiV3 implements.
Config 为 OpenApiV3 实现提供了额外的配置功能。
1
2
3
4
5
| type Contact struct {
Name string `json:"name,omitempty"`
URL string `json:"url,omitempty"`
Email string `json:"email,omitempty"`
}
|
Contact is specified by OpenAPI/Swagger standard version 3.0.
联系人由 OpenAPI/Swagger 标准版本 3.0 指定。
type Content
1
| type Content map[string]MediaType
|
Content is specified by OpenAPI/Swagger 3.0 standard.
内容由 OpenAPI/Swagger 3.0 标准指定。
type Discriminator
1
2
3
4
| type Discriminator struct {
PropertyName string `json:"propertyName"`
Mapping map[string]string `json:"mapping,omitempty"`
}
|
Discriminator is specified by OpenAPI/Swagger standard version 3.0.
鉴别器由 OpenAPI/Swagger 标准版本 3.0 指定。
type Encoding
1
2
3
4
5
6
7
| type Encoding struct {
ContentType string `json:"contentType,omitempty"`
Headers Headers `json:"headers,omitempty"`
Style string `json:"style,omitempty"`
Explode *bool `json:"explode,omitempty"`
AllowReserved bool `json:"allowReserved,omitempty"`
}
|
Encoding is specified by OpenAPI/Swagger 3.0 standard.
编码由 OpenAPI/Swagger 3.0 标准指定。
type Example
1
2
3
4
5
6
| type Example struct {
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Value interface{} `json:"value,omitempty"`
ExternalValue string `json:"externalValue,omitempty"`
}
|
Example is specified by OpenAPI/Swagger 3.0 standard.
示例由 OpenAPI/Swagger 3.0 标准指定。
type ExampleRef
1
2
3
4
| type ExampleRef struct {
Ref string
Value *Example
}
|
(ExampleRef) MarshalJSON
1
| func (r ExampleRef) MarshalJSON() ([]byte, error)
|
type Examples
1
| type Examples map[string]*ExampleRef
|
type ExternalDocs
1
2
3
4
| type ExternalDocs struct {
URL string `json:"url,omitempty"`
Description string `json:"description,omitempty"`
}
|
ExternalDocs is specified by OpenAPI/Swagger standard version 3.0.
ExternalDocs 由 OpenAPI/Swagger 标准版本 3.0 指定。
(*ExternalDocs) UnmarshalValue
1
| func (ed *ExternalDocs) UnmarshalValue(value interface{}) error
|
1
2
3
| type Header struct {
Parameter
}
|
Header is specified by OpenAPI/Swagger 3.0 standard. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#headerObject
标头由 OpenAPI/Swagger 3.0 标准指定。请参阅 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#headerObject
1
2
3
4
| type HeaderRef struct {
Ref string
Value *Header
}
|
1
| func (r HeaderRef) MarshalJSON() ([]byte, error)
|
1
| type Headers map[string]HeaderRef
|
type Info
1
2
3
4
5
6
7
8
| type Info struct {
Title string `json:"title"`
Description string `json:"description,omitempty"`
TermsOfService string `json:"termsOfService,omitempty"`
Contact *Contact `json:"contact,omitempty"`
License *License `json:"license,omitempty"`
Version string `json:"version"`
}
|
Info is specified by OpenAPI/Swagger standard version 3.0.
信息由 OpenAPI/Swagger 标准版本 3.0 指定。
type License
1
2
3
4
| type License struct {
Name string `json:"name"`
URL string `json:"url,omitempty"`
}
|
License is specified by OpenAPI/Swagger standard version 3.0.
许可证由 OpenAPI/Swagger 标准版本 3.0 指定。
type Link
1
2
3
4
5
6
7
8
| type Link struct {
OperationID string `json:"operationId,omitempty"`
OperationRef string `json:"operationRef,omitempty"`
Description string `json:"description,omitempty"`
Parameters map[string]interface{} `json:"parameters,omitempty"`
Server *Server `json:"server,omitempty"`
RequestBody interface{} `json:"requestBody,omitempty"`
}
|
Link is specified by OpenAPI/Swagger standard version 3.0.
链接由 OpenAPI/Swagger 标准版本 3.0 指定。
type LinkRef
1
2
3
4
| type LinkRef struct {
Ref string
Value *Link
}
|
(LinkRef) MarshalJSON
1
| func (r LinkRef) MarshalJSON() ([]byte, error)
|
type Links
1
| type Links map[string]LinkRef
|
1
2
3
4
5
6
| type MediaType struct {
Schema *SchemaRef `json:"schema,omitempty"`
Example interface{} `json:"example,omitempty"`
Examples Examples `json:"examples,omitempty"`
Encoding map[string]*Encoding `json:"encoding,omitempty"`
}
|
MediaType is specified by OpenAPI/Swagger 3.0 standard.
MediaType 由 OpenAPI/Swagger 3.0 标准指定。
type OAuthFlow
1
2
3
4
5
6
| type OAuthFlow struct {
AuthorizationURL string `json:"authorizationUrl,omitempty"`
TokenURL string `json:"tokenUrl,omitempty"`
RefreshURL string `json:"refreshUrl,omitempty"`
Scopes map[string]string `json:"scopes"`
}
|
type OAuthFlows
1
2
3
4
5
6
| type OAuthFlows struct {
Implicit *OAuthFlow `json:"implicit,omitempty"`
Password *OAuthFlow `json:"password,omitempty"`
ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty"`
AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty"`
}
|
type OpenApiV3
1
2
3
4
5
6
7
8
9
10
11
| type OpenApiV3 struct {
Config Config `json:"-"`
OpenAPI string `json:"openapi"`
Components Components `json:"components,omitempty"`
Info Info `json:"info"`
Paths Paths `json:"paths"`
Security *SecurityRequirements `json:"security,omitempty"`
Servers *Servers `json:"servers,omitempty"`
Tags *Tags `json:"tags,omitempty"`
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
}
|
OpenApiV3 is the structure defined from: https://swagger.io/specification/ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md
OpenApiV3 是定义如下的结构： https://swagger.io/specification/ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md
func New
New creates and returns an OpenApiV3 implements object.
New 创建并返回 OpenApiV3 实现对象。
(*OpenApiV3) Add
1
| func (oai *OpenApiV3) Add(in AddInput) error
|
Add adds an instance of struct or a route function to OpenApiV3 definition implements.
Add 将 struct 的实例或路由函数添加到 OpenApiV3 定义实现中。
(OpenApiV3) String
1
| func (oai OpenApiV3) String() string
|
type Operation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| type Operation struct {
Tags []string `json:"tags,omitempty"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
OperationID string `json:"operationId,omitempty"`
Parameters Parameters `json:"parameters,omitempty"`
RequestBody *RequestBodyRef `json:"requestBody,omitempty"`
Responses Responses `json:"responses"`
Deprecated bool `json:"deprecated,omitempty"`
Callbacks *Callbacks `json:"callbacks,omitempty"`
Security *SecurityRequirements `json:"security,omitempty"`
Servers *Servers `json:"servers,omitempty"`
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
XExtensions XExtensions `json:"-"`
}
|
Operation represents “operation” specified by OpenAPI/Swagger 3.0 standard.
Operation 表示 OpenAPI/Swagger 3.0 标准指定的“操作”。
(Operation) MarshalJSON
1
| func (o Operation) MarshalJSON() ([]byte, error)
|
type Parameter
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| type Parameter struct {
Name string `json:"name,omitempty"`
In string `json:"in,omitempty"`
Description string `json:"description,omitempty"`
Style string `json:"style,omitempty"`
Explode *bool `json:"explode,omitempty"`
AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`
AllowReserved bool `json:"allowReserved,omitempty"`
Deprecated bool `json:"deprecated,omitempty"`
Required bool `json:"required,omitempty"`
Schema *SchemaRef `json:"schema,omitempty"`
Example interface{} `json:"example,omitempty"`
Examples *Examples `json:"examples,omitempty"`
Content *Content `json:"content,omitempty"`
XExtensions XExtensions `json:"-"`
}
|
Parameter is specified by OpenAPI/Swagger 3.0 standard. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameterObject
参数由 OpenAPI/Swagger 3.0 标准指定。请参阅 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameterObject
(Parameter) MarshalJSON
1
| func (p Parameter) MarshalJSON() ([]byte, error)
|
type ParameterRef
1
2
3
4
| type ParameterRef struct {
Ref string
Value *Parameter
}
|
(ParameterRef) MarshalJSON
1
| func (r ParameterRef) MarshalJSON() ([]byte, error)
|
type Parameters
1
| type Parameters []ParameterRef
|
Parameters is specified by OpenAPI/Swagger 3.0 standard.
参数由 OpenAPI/Swagger 3.0 标准指定。
type ParametersMap
1
| type ParametersMap map[string]*ParameterRef
|
type Path
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| type Path struct {
Ref string `json:"$ref,omitempty"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Connect *Operation `json:"connect,omitempty"`
Delete *Operation `json:"delete,omitempty"`
Get *Operation `json:"get,omitempty"`
Head *Operation `json:"head,omitempty"`
Options *Operation `json:"options,omitempty"`
Patch *Operation `json:"patch,omitempty"`
Post *Operation `json:"post,omitempty"`
Put *Operation `json:"put,omitempty"`
Trace *Operation `json:"trace,omitempty"`
Servers Servers `json:"servers,omitempty"`
Parameters Parameters `json:"parameters,omitempty"`
XExtensions XExtensions `json:"-"`
}
|
Path is specified by OpenAPI/Swagger standard version 3.0.
路径由 OpenAPI/Swagger 标准版本 3.0 指定。
(Path) MarshalJSON
1
| func (p Path) MarshalJSON() ([]byte, error)
|
MarshalJSON implements the interface MarshalJSON for json.Marshal.
MarshalJSON 实现 json 的接口 MarshalJSON。元帅。
type Paths
1
| type Paths map[string]Path
|
Paths are specified by OpenAPI/Swagger standard version 3.0.
路径由 OpenAPI/Swagger 标准版本 3.0 指定。
type RequestBodies
1
| type RequestBodies map[string]*RequestBodyRef
|
type RequestBody
1
2
3
4
5
| type RequestBody struct {
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
Content Content `json:"content,omitempty"`
}
|
RequestBody is specified by OpenAPI/Swagger 3.0 standard.
RequestBody 由 OpenAPI/Swagger 3.0 标准指定。
type RequestBodyRef
1
2
3
4
| type RequestBodyRef struct {
Ref string
Value *RequestBody
}
|
(RequestBodyRef) MarshalJSON
1
| func (r RequestBodyRef) MarshalJSON() ([]byte, error)
|
type Response
1
2
3
4
5
6
7
| type Response struct {
Description string `json:"description"`
Headers Headers `json:"headers,omitempty"`
Content Content `json:"content,omitempty"`
Links Links `json:"links,omitempty"`
XExtensions XExtensions `json:"-"`
}
|
Response is specified by OpenAPI/Swagger 3.0 standard.
响应由 OpenAPI/Swagger 3.0 标准指定。
(Response) MarshalJSON
1
| func (r Response) MarshalJSON() ([]byte, error)
|
type ResponseRef
1
2
3
4
| type ResponseRef struct {
Ref string
Value *Response
}
|
(ResponseRef) MarshalJSON
1
| func (r ResponseRef) MarshalJSON() ([]byte, error)
|
type Responses
1
| type Responses map[string]ResponseRef
|
Responses is specified by OpenAPI/Swagger 3.0 standard.
响应由 OpenAPI/Swagger 3.0 标准指定。
type Schema
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
| type Schema struct {
OneOf SchemaRefs `json:"oneOf,omitempty"`
AnyOf SchemaRefs `json:"anyOf,omitempty"`
AllOf SchemaRefs `json:"allOf,omitempty"`
Not *SchemaRef `json:"not,omitempty"`
Type string `json:"type,omitempty"`
Title string `json:"title,omitempty"`
Format string `json:"format,omitempty"`
Description string `json:"description,omitempty"`
Enum []interface{} `json:"enum,omitempty"`
Default interface{} `json:"default,omitempty"`
Example interface{} `json:"example,omitempty"`
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
UniqueItems bool `json:"uniqueItems,omitempty"`
ExclusiveMin bool `json:"exclusiveMinimum,omitempty"`
ExclusiveMax bool `json:"exclusiveMaximum,omitempty"`
Nullable bool `json:"nullable,omitempty"`
ReadOnly bool `json:"readOnly,omitempty"`
WriteOnly bool `json:"writeOnly,omitempty"`
AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`
XML interface{} `json:"xml,omitempty"`
Deprecated bool `json:"deprecated,omitempty"`
Min *float64 `json:"minimum,omitempty"`
Max *float64 `json:"maximum,omitempty"`
MultipleOf *float64 `json:"multipleOf,omitempty"`
MinLength uint64 `json:"minLength,omitempty"`
MaxLength *uint64 `json:"maxLength,omitempty"`
Pattern string `json:"pattern,omitempty"`
MinItems uint64 `json:"minItems,omitempty"`
MaxItems *uint64 `json:"maxItems,omitempty"`
Items *SchemaRef `json:"items,omitempty"`
Required []string `json:"required,omitempty"`
Properties Schemas `json:"properties,omitempty"`
MinProps uint64 `json:"minProperties,omitempty"`
MaxProps *uint64 `json:"maxProperties,omitempty"`
AdditionalProperties *SchemaRef `json:"additionalProperties,omitempty"`
Discriminator *Discriminator `json:"discriminator,omitempty"`
XExtensions XExtensions `json:"-"`
ValidationRules string `json:"-"`
}
|
Schema is specified by OpenAPI/Swagger 3.0 standard.
架构由 OpenAPI/Swagger 3.0 标准指定。
(*Schema) Clone
1
| func (s *Schema) Clone() *Schema
|
Clone only clones necessary attributes. TODO clone all attributes, or improve package deepcopy.
仅克隆必要的属性。TODO 克隆所有属性，或改进包 deepcopy。
(Schema) MarshalJSON
1
| func (s Schema) MarshalJSON() ([]byte, error)
|
type SchemaRef
1
2
3
4
| type SchemaRef struct {
Ref string
Value *Schema
}
|
(SchemaRef) MarshalJSON
1
| func (r SchemaRef) MarshalJSON() ([]byte, error)
|
type SchemaRefs
1
| type SchemaRefs []SchemaRef
|
type Schemas
1
2
3
| type Schemas struct {
// contains filtered or unexported fields
}
|
(*Schemas) Clone
1
| func (s *Schemas) Clone() Schemas
|
(*Schemas) Get
1
| func (s *Schemas) Get(name string) *SchemaRef
|
(*Schemas) Iterator
1
| func (s *Schemas) Iterator(f func(key string, ref SchemaRef) bool)
|
(*Schemas) Map
1
| func (s *Schemas) Map() map[string]SchemaRef
|
(Schemas) MarshalJSON
1
| func (s Schemas) MarshalJSON() ([]byte, error)
|
(*Schemas) Removes
1
| func (s *Schemas) Removes(names []interface{})
|
(*Schemas) Set
1
| func (s *Schemas) Set(name string, ref SchemaRef)
|
type SecurityRequirement
1
| type SecurityRequirement map[string][]string
|
type SecurityRequirements
1
| type SecurityRequirements []SecurityRequirement
|
type SecurityScheme
1
2
3
4
5
6
7
8
9
10
| type SecurityScheme struct {
Type string `json:"type,omitempty"`
Description string `json:"description,omitempty"`
Name string `json:"name,omitempty"`
In string `json:"in,omitempty"`
Scheme string `json:"scheme,omitempty"`
BearerFormat string `json:"bearerFormat,omitempty"`
Flows *OAuthFlows `json:"flows,omitempty"`
OpenIdConnectUrl string `json:"openIdConnectUrl,omitempty"`
}
|
type SecuritySchemeRef
1
2
3
4
| type SecuritySchemeRef struct {
Ref string
Value *SecurityScheme
}
|
(SecuritySchemeRef) MarshalJSON
1
| func (r SecuritySchemeRef) MarshalJSON() ([]byte, error)
|
type SecuritySchemes
1
| type SecuritySchemes map[string]SecuritySchemeRef
|
type Server
1
2
3
4
5
| type Server struct {
URL string `json:"url"`
Description string `json:"description,omitempty"`
Variables map[string]*ServerVariable `json:"variables,omitempty"`
}
|
Server is specified by OpenAPI/Swagger standard version 3.0.
服务器由 OpenAPI/Swagger 标准版本 3.0 指定。
type ServerVariable
1
2
3
4
5
| type ServerVariable struct {
Enum []string `json:"enum,omitempty"`
Default string `json:"default,omitempty"`
Description string `json:"description,omitempty"`
}
|
ServerVariable is specified by OpenAPI/Swagger standard version 3.0.
ServerVariable 由 OpenAPI/Swagger 标准版本 3.0 指定。
type Servers
Servers is specified by OpenAPI/Swagger standard version 3.0.
服务器由 OpenAPI/Swagger 标准版本 3.0 指定。
type Tag
1
2
3
4
5
| type Tag struct {
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
}
|
Tag is specified by OpenAPI/Swagger 3.0 standard.
标签由 OpenAPI/Swagger 3.0 标准指定。
Tags is specified by OpenAPI/Swagger 3.0 standard.
标签由 OpenAPI/Swagger 3.0 标准指定。
type XExtensions
1
| type XExtensions map[string]string
|
XExtensions stores the x- custom extensions.
XExtensions 存储 x- 自定义扩展。