openapi

Documentation

Overview

Package openapi 实现 openapi 的相关数据类型

https://github.com/OAI/OpenAPI-Specification

Index

• Constants
• func IsWellDataType(typ string) bool
• func JSON(doc *doc.Doc) ([]byte, error)
• func YAML(doc *doc.Doc) ([]byte, error)
• type Callback
• type Components
  • func (c *Components) Sanitize() *errors.Error
• type Contact
  • func (c *Contact) Sanitize() *errors.Error
• type Description
• type Discriminator
• type Encoding
  • func (en *Encoding) Sanitize() *errors.Error
• type Example
• type ExampleValue
• type ExternalDocumentation
  • func (ext *ExternalDocumentation) Sanitize() *errors.Error
• type Header
  • func (h *Header) Sanitize() *errors.Error
• type Info
  • func (info *Info) Sanitize() *errors.Error
• type License
  • func (l *License) Sanitize() *errors.Error
• type Link
  • func (l *Link) Sanitize() *errors.Error
• type MediaType
  • func (mt *MediaType) Sanitize() *errors.Error
• type OAuthFlow
• type OAuthFlows
• type OpenAPI
  • func (oa *OpenAPI) Sanitize() *errors.Error
• type Operation
• type Parameter
  • func (p *Parameter) Sanitize() *errors.Error
• type PathItem
• type RequestBody
  • func (req *RequestBody) Sanitize() *errors.Error
• type Response
  • func (resp *Response) Sanitize() *errors.Error
• type Sanitizer
• type Schema
  • func (s *Schema) Sanitize() *errors.Error
• type SecurityRequirement
• type SecurityScheme
• type Server
  • func (srv *Server) Sanitize() *errors.Error
• type ServerVariable
  • func (v *ServerVariable) Sanitize() *errors.Error
• type Style
  • func (style *Style) Sanitize() *errors.Error
• type Tag
  • func (tag *Tag) Sanitize() *errors.Error
• type XML

Constants

const (
	ParameterINPath   = "path"
	ParameterINQuery  = "query"
	ParameterINHeader = "header"
	ParameterINcookie = "cookie"
)

Parameter.IN 的可选值

const (
	TypeInt      = doc.Integer
	TypeLong     = "long"
	TypeFloat    = "float"
	TypeDouble   = "double"
	TypeString   = doc.String
	TypeBool     = doc.Bool
	TypePassword = "password"
)

Schema.Type 需要的一些预定义数据类型

const (
	SecurityInQuery  = "query"
	SecurityInHeader = "header"
	SecurityInCookie = "cookie"
)

SecurityScheme.IN 的可选值

const (
	SecurityTypeAPIKey        = "apikey"
	SecurityTypeHTTP          = "http"
	SecurityTypeOAuth2        = "oauth2"
	SecurityTypeOpenIDConnect = "openIdConnect"
)

Security.Type 的可选值

const (
	StyleMatrix         = "matrix"
	StyleLabel          = "label"
	StyleForm           = "form"
	StyleSimple         = "simple"
	StyleSpaceDelimited = "spaceDelimited"
	StylePipeDelimited  = "pipeDelimited"
	StyleDeepObject     = "deepObject"
)

Style.Style 的可选值

const LatestVersion = "3.0.1"

LatestVersion openapi 最新的版本号

Functions

func IsWellDataType

func IsWellDataType(typ string) bool

IsWellDataType 是否为一个正常的数据类型

func JSON

func JSON(doc *doc.Doc) ([]byte, error)

JSON 输出 JSON 格式数据

func YAML

func YAML(doc *doc.Doc) ([]byte, error)

YAML 输出 YAML 格式数据

Types

type Callback

type Callback PathItem

Callback Object

NOTE: 暂时未用到

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]*RequestBody    `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
	Headers         map[string]*Header         `json:"headers,omitempty" yaml:"headers,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `json:"securitySechemes,omitempty" yaml:"securitySechemes,omitempty"`
	Links           map[string]*Link           `json:"links,omitempty" yaml:"links,omitempty"`
	Callbacks       map[string]*Callback       `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
}

Components 可复用的对象

func (*Components) Sanitize

func (c *Components) Sanitize() *errors.Error

Sanitize 数据检测

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"`
}

Contact 描述联系方式

func (*Contact) Sanitize

func (c *Contact) Sanitize() *errors.Error

Sanitize 数据检测

type Description

type Description = doc.Markdown

Description 表示描述类型 可以采用 MD 格式

type Discriminator

type Discriminator struct {
	PropertyName string            `json:"propertyName" yaml:"propertyName"`
	Mapping      map[string]string `json:"mapping,omitempty" yaml:"mapping,omitempty"`
}

Discriminator Object

NOTE: 暂时未用到。

type Encoding

type Encoding struct {
	Style
	ContentType string             `json:"contentType,omitempty" yaml:"contentType,omitempty"`
	Headers     map[string]*Header `json:"headers,omitempty" yaml:"headers,omitempty"`
}

Encoding 定义编码

对父对象中的 Schema 中的一些字段的特殊定义

func (*Encoding) Sanitize

func (en *Encoding) Sanitize() *errors.Error

Sanitize 数据检测

type Example

type Example struct {
	Summary       string       `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description   Description  `json:"description,omitempty" yaml:"description,omitempty"`
	Value         ExampleValue `json:"value,omitempty" yaml:"value,omitempty"`
	ExternalValue string       `json:"external,omitempty" yaml:"external,omitempty"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
}

Example 示例代码

type ExampleValue

type ExampleValue string

ExampleValue 表示示例的内容类型。

type ExternalDocumentation

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

ExternalDocumentation 引用外部资源的扩展文档

func (*ExternalDocumentation) Sanitize

func (ext *ExternalDocumentation) Sanitize() *errors.Error

Sanitize 数据检测

type Header

type Header Parameter

Header 即 Parameter 的别名，但 Name 字段必须不能存在。

func (*Header) Sanitize

func (h *Header) Sanitize() *errors.Error

Sanitize 对数据进行验证

type Info

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

Info 接口文档的基本信息

func (*Info) Sanitize

func (info *Info) Sanitize() *errors.Error

Sanitize 数据检测

type License

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

License 授权信息

func (*License) Sanitize

func (l *License) Sanitize() *errors.Error

Sanitize 数据检测

type Link

type Link struct {
	OperationRef string            `json:"operationRef,omitempty" yaml:"operationRef,omitempty"`
	OperationID  string            `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters   map[string]string `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody  map[string]string `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Description  Description       `json:"description,omitempty" yaml:"description,omitempty"`
	Server       *Server           `json:"server,omitempty" yaml:"server,omitempty"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
}

Link 链接信息

func (*Link) Sanitize

func (l *Link) Sanitize() *errors.Error

Sanitize 数据检测

type MediaType

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

MediaType 媒体类型

func (*MediaType) Sanitize

func (mt *MediaType) Sanitize() *errors.Error

Sanitize 数据检测

type OAuthFlow

type OAuthFlow struct {
	AuthorizationURL string            `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
	RefreshURL       string            `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
	Scopes           map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
}

OAuthFlow Object

type OAuthFlows

type OAuthFlows struct {
	Implicit          *OAuthFlow `json:"implicit,omitempty" yaml:"implicit,omitempty"`
	Password          *OAuthFlow `json:"password,omitempty" yaml:"password,omitempty"`
	ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty" yaml:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty" yaml:"authorizationCode,omitempty"`
}

OAuthFlows Object

type OpenAPI

type OpenAPI 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"`
	Security     []*SecurityRequirement `json:"security,omitempty" yaml:"security,omitempty"`
	Tags         []*Tag                 `json:"tags,omitempty" yaml:"tags,omitempty"`
	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
}

OpenAPI openAPI 的根对象

func (*OpenAPI) Sanitize

func (oa *OpenAPI) Sanitize() *errors.Error

Sanitize 数据检测

type Operation

type Operation struct {
	Tags         []string               `json:"tags,omitempty" yaml:"tags,omitempty"`
	Summary      string                 `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description  Description            `json:"description,omitempty" yaml:"description,omitempty"`
	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty" yaml:"externalDocs,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"`
	Callbacks    map[string]*Callback   `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
	Deprecated   bool                   `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	Security     []*SecurityRequirement `json:"security,omitempty" yaml:"security,omitempty"`
	Servers      []*Server              `json:"servers,omitempty" yaml:"servers,omitempty"`
}

Operation 描述对某一个资源的操作具体操作

type Parameter

type Parameter struct {
	Style
	Name            string                `json:"name,omitempty" yaml:"name,omitempty"`
	IN              string                `json:"in,omitempty" yaml:"in,omitempty"`
	Description     Description           `json:"description,omitempty" yaml:"description,omitempty"`
	Required        bool                  `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated      bool                  `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmptyValue bool                  `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Schema          *Schema               `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example         ExampleValue          `json:"example,omitempty" yaml:"example,omitempty"`
	Examples        map[string]*Example   `json:"examples,omitempty" yaml:"examples,omitempty"`
	Content         map[string]*MediaType `json:"content,omitempty" yaml:"content,omitempty"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
}

Parameter 参数信息 可同时作用于路径参数、请求参数、报头内容和 Cookie 值。

func (*Parameter) Sanitize

func (p *Parameter) Sanitize() *errors.Error

Sanitize 对数据进行验证

type PathItem

type PathItem struct {
	Ref         string       `json:"ref,omitempty" yaml:"ref,omitempty"`
	Summary     string       `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description Description  `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"`
}

PathItem 每一条路径的详细描述信息

type RequestBody

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

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
}

RequestBody 请求内容

func (*RequestBody) Sanitize

func (req *RequestBody) Sanitize() *errors.Error

Sanitize 数据检测

type Response

type Response struct {
	Description Description           `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"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
}

Response 每个 API 的返回信息

func (*Response) Sanitize

func (resp *Response) Sanitize() *errors.Error

Sanitize 数据检测

type Sanitizer

type Sanitizer interface {
	Sanitize() *errors.Error
}

Sanitizer 数据验证接口

type Schema

type Schema struct {
	doc.Schema
	Discriminator *Discriminator         `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
	XML           *XML                   `json:"xml,omitempty" yaml:"xml,omitempty"`
	ExternalDocs  *ExternalDocumentation `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	Example       ExampleValue           `json:"example,omitempty" yaml:"example,omitempty"`
	Deprecated    bool                   `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
}

Schema 定义了输出和输出的数据类型

func (*Schema) Sanitize

func (s *Schema) Sanitize() *errors.Error

Sanitize 数据检测

type SecurityRequirement

type SecurityRequirement map[string][]string

SecurityRequirement Object

键名指向的是 Components.SecuritySchemes 中的名称。 若 SecurityScheme.Type 是 oauth2 或是 openIDConnect， 则 SecurityRequirement 的键值必须是个空值，否则键值为一个 scope 列表。

type SecurityScheme

type SecurityScheme struct {
	Type             string      `json:"type" yaml:"type"`
	Description      Description `json:"description,omitempty" yaml:"description,omitempty"`
	Name             string      `json:"name" yaml:"name"` // 报头或是 cookie 的名称
	IN               string      `json:"in" yaml:"in"`     // 位置, header, query 和 cookie
	Scheme           string      `json:"scheme" yaml:"scheme"`
	BearerFormat     string      `json:"bearerFormat,omitempty" yaml:"bearerFormat,omitempty"`
	Flows            *OAuthFlows `json:"flows" yaml:"flows"`
	OpenIDConnectURL string      `json:"openIdConnectUrl" yaml:"openIdConnectUrl"`

	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
}

SecurityScheme Object

type Server

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

Server 服务器描述信息

func (*Server) Sanitize

func (srv *Server) Sanitize() *errors.Error

Sanitize 数据检测

type ServerVariable

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

ServerVariable Server 中 URL 模板中对应的参数变量值

func (*ServerVariable) Sanitize

func (v *ServerVariable) Sanitize() *errors.Error

Sanitize 数据检测

type Style

type Style struct {
	Style         string `json:"style,omitempty" yaml:"style,omitempty"`
	Explode       bool   `json:"explode,omitempty" yaml:"explode,omitempty"`
	AllowReserved bool   `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
}

Style 民法风格的相关定义

不直接作用于对象，被部分对象包含，比如 Encoding 和 Parameter 等

func (*Style) Sanitize

func (style *Style) Sanitize() *errors.Error

Sanitize 对数据进行验证

type Tag

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

Tag 标签内容

func (*Tag) Sanitize

func (tag *Tag) Sanitize() *errors.Error

Sanitize 数据检测

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"`
}

XML 将 Schema 转换为 XML 的相关声明