Swagger 2.0 规范理解
宰父嘉胜
Swagger 2.0
Swagger规范是REST API的API描述格式，API规范可以用YAML或JSON编写，格式易于学习，并且对人和机器都可读，本文主要基于YAML示例 (json 同理试用），其yaml样本如下：
顶级标签
parameters: # 请求体公共参数定义，使用如下格式引用：
# parameters:
# - $ref: "traffic.yaml#/parameters/get-topfc-request"
responses: # 响应体公共参数定义
# schema:
# - $ref: "traffic.yaml#/parameters/get-topfc-request"
definitions: # 定义对象的公共结构
# schema:
# - $ref: "traffic.yaml#/parameters/get-topfc-request"
元数据
元数据主要包括一些REST 接口的描述信息，包括如下信息：
# “” 或者 ‘’ 都可以表示值，但是“ ” 不进行 特殊字符转义 ，‘’ 进行特殊字符转义
swagger: "2.0" # 每个Swagger规范都以Swagger版本开始。 2.0 表示 swagger 规范版本
info: # 标题信息
description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters." #（此标签可选）
version: "1.0.0" # 表示该rest API版本
title: "Swagger Petstore" #rest api 接口标题名
termsOfService: "http://swagger.io/terms/" #服务条款
contact: # 联系电话
email: "apiteam@swagger.io"
license: #许可证信息
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
基本网址
host: "petstore.swagger.io" # 为API提供服务的主机的域名或IP地址（IPv4）如果与方案的默认端口（对于HTTP为80，对于HTTPS为443）不同，则它可能包含端口号
# 请注意，必须仅是主机域名和IP地址，不可以包含协议名：http（s）：//或 其服务端的子路径。
# 如未指定，则假定为提供API 文档所在的主机
# http://api.example.com (x)
# example.com/api/v1 (x)
basePath: "/v2" # 基本网址 必须以"/"开头 相对于主机根目录的所有API路径的URL前缀 不指定默认为"/""
schemes: #请求支持协议 http https wss ws
- "https"
- "http"
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-8OQf7Ozw-1615865552000)(E:\typora\swagger\swagger-基本网址.PNG)]
标签信息
tags: # 标签信息
- name: "pet"
description: "Everything about your Pets"
externalDocs:
description: "Find out more"
url: "http://swagger.io"
- name: "store"
description: "Access to Petstore orders"
- name: "user"
description: "Operations about user"
externalDocs:
description: "Find out more about our store"
url: "http://swagger.io"
媒体类型（MIME TYPE)
API接收和返回的数据媒体类型，如常见的 JSON和XML。可以在根级目录定义定义全局媒体类型，其所有API都会继承（ inherite) 。而且每一个API 也可以定义自己的媒体类型，会覆盖根级目录定义的。
consumes: # 定义入参值
- application/json
- application/xml
produces: # 定义返回值，及响应数据
- application/json
- application/xml
#consumes和produces 支持 RFC6838标准 包括如下：
application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain
charset=utf-8
text/html
application/pdf
image/png
# 以及一些特定供应商的MIMETYPE
application/vnd.mycompany.myapp.v2+json
application/vnd.ms-excel
application/vnd.openstreetmap.data+xml
application/vnd.github-issue.text+json
application/vnd.github.v3.diff
image/vnd.djvu
路径与操作
paths 部分定义了API 中路径、端点，及其支持的http 或 wss方法，所有方法都是相对路径。
paths:
/ping: # 必须以"/" 开头 支持模板定义 可以使用大括号{}将URL的一部分标记为路径参数
# /organizations/{orgId}/members/{memberId}
# 操作方式： swagger 2.0 支持 get，post，put，patch，delete，head，options 操作
# 每个路径支持多个操作方式。
# Swagger将路径和操作方式定义为唯一操作。（重点理解）
# 意味着不允许使用同一路径的两个GET或POST方法-即使它们具有不同的参数（参数对唯一性没有影响）
GET /users?firstName=value&lastName=value
GET /users?role=value
# 以上两个url 代表同一个操作,不允许这样定义
#正确的是如下所示：
GET /users/findByName?firstName=value&lastName=value
GET /users/findByRole?role=value
# 路径里面不允许包含查询字符串参数 ，其查询参数应该定义在parameters:结构里
# /users?role={role} (x)
#正确的是如下结构：
/users:
get:
parameters:
- in: query
name: role
type: string
enum: [user, poweruser, admin]
required: false
参数 （parameters)
parameters:
- in: query # "-" 表示列表元素,parameters 是一个list，所以每一个参数都需要携带"-"
# 参数位置 表示该参数位于 api 那个部分 可以有path query body header form
# query: 查询参数，例如/users?role=1&limit=50 只支持基本数据类型，可以是array,但是item必须是基本数据类型
# path: 路径参数，例如/users/{id}
# body: 请求体参数，post put patch 请求主体参数
# header: http 请求头参数，例如X-MyHeader: Value
# formData：表单参数
name: role
type: integer
required: true
description: Numeric ID of the user to get.
- in: query
name: limit
default: 0 # 默认值
minimum: 1 # 最小值
maximum: 100 # 最大值
enum: [1,20，50，100]
type: integer
- in: path # 例如 /users/{id} /cars/{carId}/drivers/{driverId}
#/users/12,34,56 可以是多个值，定义为array
name: id
type: integer
required: true # 路径参数要求必须是true
- in: header # http 请求头参数
name: X-Request-ID
type: string
- in: formData #
name: name
type: string
description: A person's name.
- in: query
name: color
type: array
collectionFormat: csv # arry 转换url后分隔符定义
items:
type: string
enum: [black, white, gray] # 将列表值限定为枚举值
# Path, query, header and form parameters 都可以接受列表参数
GET /users/12,34,56,78 # path url
GET /resource?param=value1,value2,value3 # query url
GET /resource?param=value1¶m=value2¶m=value3 # query url
POST /resource # header
param=value1¶m=value2 #form
collectionFormat
| collectionFormat | Description | Example |
|---|---|---|
csv (default) | Comma-separated values. | foo,bar,baz |
ssv | Space-separated values. | foo bar baz |
tsv | Tab-separated values. | "foo\tbar\tbaz" |
pipes | Pipe-separated values. | foo|bar|baz |
multi | Multiple parameter instances rather than multiple values. This is only supported for the in: query and in: formData parameters. | foo=value&foo=another_value |
Constant Parameters
您可以将常量参数定义为必需参数，并且只能使用一个可能的值： 参照如下定义：
- in: query
name: version
type: integer
required: true
enum: [0]
# 常数参数与默认参数不同。常量参数始终由客户端发送，而默认值是客户端不发送参数时服务器使用的值。
Parameters Without a Value
查询字符串和表单数据参数只能有一个名称，没有值： 参照如下定义：
GET /foo?metadata
###########################
- in: query
name: metadata
required: true
type: boolean
allowEmptyValue: true # <-----
Common Parameters
同一路径的公共参数
公共参数，和MIME TYPE 一样，全局公共参数可以在path 下定义，则关于该path下的所有operation都可以适应该参数，并且每一个operation 可以覆盖去全局公共参数，也可以添加自己独有的参数。但不可以移除公共参数
paths:
/user/{id}:
parameters: # 全局公共参数
- in: path
name: id
type: integer
required: true
description: The user ID.
get:
summary: Gets a user by ID.
parameters: # get operation 特有参数
- in: query
name: metadata
type: boolean
required: false
description: If true, the endpoint returns only the user metadata.
responses:
200:
description: OK
patch:
summary: Updates an existing user with the specified ID.
parameters: # patch operation 可以覆盖全局参数
- in: path
name: id
required: true
description: A comma-separated list of user IDs.
type: array
items:
type: integer
collectionFormat: csv
minItems: 1
responses:
200:
description: OK
delete:
summary: Deletes the user with the specified ID.
不同路径的公共参数
可以在全局公共参数里面定义结构，采用$ref 引用该结构
parameters: # 定义公共参数
offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
# Not necessarily the same as the parameter name.
in: query
name: offset
required: false
type: integer
minimum: 0
description: The number of items to skip before starting to collect the result set.
paths:
/users:
get:
summary: Gets a list of users.
parameters:
- $ref: '#/parameters/offsetParam'
responses:
200:
description: OK
/teams:
get:
summary: Gets a list of teams.
parameters:
- $ref: '#/parameters/offsetParam'
responses:
200:
description: OK
描述响应体 RequestBody
paths:
/users:
post:
summary: Creates a new user.
consumes:
- application/json
parameters:
- in: body
name: user
description: The user to create.
schema: # 定义响应体 或者 请求体
type: object
required:
- userName
properties: # object 类型的属性列表，目测可以不添加“-”
userName:
type: string
firstName:
type: string
lastName:
type: string
responses:
201:
description: Created
# 或者"definitions" 定义响应体公共结构 使用 $ref 引用
paths:
/users:
post:
summary: Creates a new user.
consumes:
- application/json
parameters:
- in: body
name: user
description: The user to create.
schema:
$ref: '#/definitions/User' # <----------
responses:
200:
description: OK
definitions:
User: # <----------
type: object
required:
- userName
properties:
userName:
type: string
firstName:
type: string
lastName:
type: string
上传文件
响应体
produces:
- application/json
paths:
# This operation returns JSON - as defined globally above
/users:
get:
summary: Gets a list of users.
responses:
200:
description: OK
# Here, we override the "produces" array to specify other media types
/logo:
get:
summary: Gets the logo image.
produces: # 定义特殊响应体 媒体类型
- image/png
- image/gif
- image/jpeg
responses:
200: # 定义一个状态码
description: OK # 状态码必须有描述
schema: # 定义响应体结构 或者用 definitions:定义公共响应体
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
空响应体
# 某些响应（204 No Content）没有正文。为了表示响应主体为空，不定义schema结构即可。swagger会认为空响应体
responses:
204:
description: ok
默认响应
responses:
200:
description: Success
schema:
$ref: '#/definitions/User'
# Definition of all error statuses
default: # 表示 此响应码为没有单独覆盖的http状态码，统一返回此响应体
description: Unexpected error
schema:
$ref: '#/definitions/Error'
重用响应
paths:
/users:
get:
summary: Gets a list of users.
response:
200:
description: OK
schema:
$ref: '#/definitions/ArrayOfUsers'
401:
$ref: '#/responses/Unauthorized' # <-----
/users/{id}:
get:
summary: Gets a user by ID.
response:
200:
description: OK
schema:
$ref: '#/definitions/User'
401:
$ref: '#/responses/Unauthorized' # <-----
404:
$ref: '#/responses/NotFound' # <-----
# Descriptions of common responses
responses: # 定义全局响应体，可以使用$ref 引用
NotFound:
description: The specified resource was not found
schema:
$ref: '#/definitions/Error'
Unauthorized:
description: Unauthorized
schema:
$ref: '#/definitions/Error'
definitions: # 定义全局body体结构，可以使用$ref 引用
# Schema for error response body
Error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
认证
securityDefinitions: # securityDefinitions API支持的所有身份验证类型
BasicAuth:
type: basic
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read: Grants read access
write: Grants write access
admin: Grants read and write access to administrative information
paths:
/billing_info:
get:
summary: Gets the account billing info
security: # 为单个 操作进行身份认证 必须是全局身份认证定义过的
- OAuth2: [admin] # Use OAuth with a different scope
responses:
200:
description: OK
/ping:
get:
summary: Checks if the server is running
security: [] # No security
responses:
200:
description: Server is up and running
使用多种认证类型
security: # A OR B
- A
- B
security: # A AND B
- A
B
security: # (A AND B) OR (C AND D)
- A
B
- C
D
swagger: "2.0"
info:
description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters."
version: "1.0.0"
title: "Swagger Petstore"
termsOfService: "http://swagger.io/terms/"
contact:
email: "apiteam@swagger.io"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
description: "Everything about your Pets"
externalDocs:
description: "Find out more"
url: "http://swagger.io"
- name: "store"
description: "Access to Petstore orders"
- name: "user"
description: "Operations about user"
externalDocs:
description: "Find out more about our store"
url: "http://swagger.io"
schemes:
- "https"
- "http"
paths:
/pet:
post:
tags:
- "pet"
summary: "Add a new pet to the store"
description: ""
operationId: "addPet"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Pet object that needs to be added to the store"
required: true
schema:
$ref: "#/definitions/Pet"
responses:
"405":
description: "Invalid input"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
put:
tags:
- "pet"
summary: "Update an existing pet"
description: ""
operationId: "updatePet"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Pet object that needs to be added to the store"
required: true
schema:
$ref: "#/definitions/Pet"
responses:
"400":
description: "Invalid ID supplied"
"404":
description: "Pet not found"
"405":
description: "Validation exception"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
/pet/findByStatus:
get:
tags:
- "pet"
summary: "Finds Pets by status"
description: "Multiple status values can be provided with comma separated strings"
operationId: "findPetsByStatus"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "status"
in: "query"
description: "Status values that need to be considered for filter"
required: true
type: "array"
items:
type: "string"
enum:
- "available"
- "pending"
- "sold"
default: "available"
collectionFormat: "multi"
responses:
"200":
description: "successful operation"
schema:
type: "array"
items:
$ref: "#/definitions/Pet"
"400":
description: "Invalid status value"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
/pet/findByTags:
get:
tags:
- "pet"
summary: "Finds Pets by tags"
description: "Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing."
operationId: "findPetsByTags"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "tags"
in: "query"
description: "Tags to filter by"
required: true
type: "array"
items:
type: "string"
collectionFormat: "multi"
responses:
"200":
description: "successful operation"
schema:
type: "array"
items:
$ref: "#/definitions/Pet"
"400":
description: "Invalid tag value"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
deprecated: true
/pet/{petId}:
get:
tags:
- "pet"
summary: "Find pet by ID"
description: "Returns a single pet"
operationId: "getPetById"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "petId"
in: "path"
description: "ID of pet to return"
required: true
type: "integer"
format: "int64"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/Pet"
"400":
description: "Invalid ID supplied"
"404":
description: "Pet not found"
security:
- api_key: []
post:
tags:
- "pet"
summary: "Updates a pet in the store with form data"
description: ""
operationId: "updatePetWithForm"
consumes:
- "application/x-www-form-urlencoded"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "petId"
in: "path"
description: "ID of pet that needs to be updated"
required: true
type: "integer"
format: "int64"
- name: "name"
in: "formData"
description: "Updated name of the pet"
required: false
type: "string"
- name: "status"
in: "formData"
description: "Updated status of the pet"
required: false
type: "string"
responses:
"405":
description: "Invalid input"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
delete:
tags:
- "pet"
summary: "Deletes a pet"
description: ""
operationId: "deletePet"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "api_key"
in: "header"
required: false
type: "string"
- name: "petId"
in: "path"
description: "Pet id to delete"
required: true
type: "integer"
format: "int64"
responses:
"400":
description: "Invalid ID supplied"
"404":
description: "Pet not found"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
/pet/{petId}/uploadImage:
post:
tags:
- "pet"
summary: "uploads an image"
description: ""
operationId: "uploadFile"
consumes:
- "multipart/form-data"
produces:
- "application/json"
parameters:
- name: "petId"
in: "path"
description: "ID of pet to update"
required: true
type: "integer"
format: "int64"
- name: "additionalMetadata"
in: "formData"
description: "Additional data to pass to server"
required: false
type: "string"
- name: "file"
in: "formData"
description: "file to upload"
required: false
type: "file"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/ApiResponse"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
/store/inventory:
get:
tags:
- "store"
summary: "Returns pet inventories by status"
description: "Returns a map of status codes to quantities"
operationId: "getInventory"
produces:
- "application/json"
parameters: []
responses:
"200":
description: "successful operation"
schema:
type: "object"
additionalProperties:
type: "integer"
format: "int32"
security:
- api_key: []
/store/order:
post:
tags:
- "store"
summary: "Place an order for a pet"
description: ""
operationId: "placeOrder"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "order placed for purchasing the pet"
required: true
schema:
$ref: "#/definitions/Order"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/Order"
"400":
description: "Invalid Order"
/store/order/{orderId}:
get:
tags:
- "store"
summary: "Find purchase order by ID"
description: "For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions"
operationId: "getOrderById"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "orderId"
in: "path"
description: "ID of pet that needs to be fetched"
required: true
type: "integer"
maximum: 10.0
minimum: 1.0
format: "int64"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/Order"
"400":
description: "Invalid ID supplied"
"404":
description: "Order not found"
delete:
tags:
- "store"
summary: "Delete purchase order by ID"
description: "For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors"
operationId: "deleteOrder"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "orderId"
in: "path"
description: "ID of the order that needs to be deleted"
required: true
type: "integer"
minimum: 1.0
format: "int64"
responses:
"400":
description: "Invalid ID supplied"
"404":
description: "Order not found"
/user:
post:
tags:
- "user"
summary: "Create user"
description: "This can only be done by the logged in user."
operationId: "createUser"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Created user object"
required: true
schema:
$ref: "#/definitions/User"
responses:
default:
description: "successful operation"
/user/createWithArray:
post:
tags:
- "user"
summary: "Creates list of users with given input array"
description: ""
operationId: "createUsersWithArrayInput"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "List of user object"
required: true
schema:
type: "array"
items:
$ref: "#/definitions/User"
responses:
default:
description: "successful operation"
/user/createWithList:
post:
tags:
- "user"
summary: "Creates list of users with given input array"
description: ""
operationId: "createUsersWithListInput"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "List of user object"
required: true
schema:
type: "array"
items:
$ref: "#/definitions/User"
responses:
default:
description: "successful operation"
/user/login:
get:
tags:
- "user"
summary: "Logs user into the system"
description: ""
operationId: "loginUser"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "username"
in: "query"
description: "The user name for login"
required: true
type: "string"
- name: "password"
in: "query"
description: "The password for login in clear text"
required: true
type: "string"
responses:
"200":
description: "successful operation"
schema:
type: "string"
headers:
X-Rate-Limit:
type: "integer"
format: "int32"
description: "calls per hour allowed by the user"
X-Expires-After:
type: "string"
format: "date-time"
description: "date in UTC when token expires"
"400":
description: "Invalid username/password supplied"
/user/logout:
get:
tags:
- "user"
summary: "Logs out current logged in user session"
description: ""
operationId: "logoutUser"
produces:
- "application/xml"
- "application/json"
parameters: []
responses:
default:
description: "successful operation"
/user/{username}:
get:
tags:
- "user"
summary: "Get user by user name"
description: ""
operationId: "getUserByName"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "username"
in: "path"
description: "The name that needs to be fetched. Use user1 for testing. "
required: true
type: "string"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/User"
"400":
description: "Invalid username supplied"
"404":
description: "User not found"
put:
tags:
- "user"
summary: "Updated user"
description: "This can only be done by the logged in user."
operationId: "updateUser"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "username"
in: "path"
description: "name that need to be updated"
required: true
type: "string"
- in: "body"
name: "body"
description: "Updated user object"
required: true
schema:
$ref: "#/definitions/User"
responses:
"400":
description: "Invalid user supplied"
"404":
description: "User not found"
delete:
tags:
- "user"
summary: "Delete user"
description: "This can only be done by the logged in user."
operationId: "deleteUser"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "username"
in: "path"
description: "The name that needs to be deleted"
required: true
type: "string"
responses:
"400":
description: "Invalid username supplied"
"404":
description: "User not found"
securityDefinitions:
petstore_auth:
type: "oauth2"
authorizationUrl: "http://petstore.swagger.io/oauth/dialog"
flow: "implicit"
scopes:
write:pets: "modify pets in your account"
read:pets: "read your pets"
api_key:
type: "apiKey"
name: "api_key"
in: "header"
definitions:
Order:
type: "object"
properties:
id:
type: "integer"
format: "int64"
petId:
type: "integer"
format: "int64"
quantity:
type: "integer"
format: "int32"
shipDate:
type: "string"
format: "date-time"
status:
type: "string"
description: "Order Status"
enum:
- "placed"
- "approved"
- "delivered"
complete:
type: "boolean"
default: false
xml:
name: "Order"
Category:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Category"
User:
type: "object"
properties:
id:
type: "integer"
format: "int64"
username:
type: "string"
firstName:
type: "string"
lastName:
type: "string"
email:
type: "string"
password:
type: "string"
phone:
type: "string"
userStatus:
type: "integer"
format: "int32"
description: "User Status"
xml:
name: "User"
Tag:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Tag"
Pet:
type: "object"
required:
- "name"
- "photoUrls"
properties:
id:
type: "integer"
format: "int64"
category:
$ref: "#/definitions/Category"
name:
type: "string"
example: "doggie"
photoUrls:
type: "array"
xml:
name: "photoUrl"
wrapped: true
items:
type: "string"
tags:
type: "array"
xml:
name: "tag"
wrapped: true
items:
$ref: "#/definitions/Tag"
status:
type: "string"
description: "pet status in the store"
enum:
- "available"
- "pending"
- "sold"
xml:
name: "Pet"
ApiResponse:
type: "object"
properties:
code:
type: "integer"
format: "int32"
type:
type: "string"
message:
type: "string"
externalDocs:
description: "Find out more about Swagger"
url: "http://swagger.io"
类似资料：