OpenAPI 是业界标准的 RESTful API 规范。
OpenAPI 规范，又称 OpenAPI Specification 或 OAS。
这是一份语言无关的规范，可以被工具解析并生成文档、代码等。
目前规范有 2.0 （Swagger 规范）和 3.0 （OpenAPI 规范）版本，本文描述的是 2.0 版本。
文档示例可以查看
Swagger Editor
:
RESETful API
通过接口对资源执行各种操作。
包含
{}
的路径，花括号标记的内容可被参数路径替换。
Mime 类型
Mime 类型定义遵从
RFC 6838
，常见有：
text/plain; charset=utf-8
application/json
HTTP 状态码
状态码表明接口执行状态，可用状态码可查看 RFC 7231 和 IANA Status Code Registry。
遵从 Swagger 规范的 API 文档可以是一个 JSON 或 YAML 格式的文件。
所有属性名都是大小写敏感的。
API 文档是一个单一的文件，但部分定义可以被拆分到不同文件。
通常 API 文档被命名为 swagger.json 或 swagger.yaml。
数据类型可以是原始数据类型或自定义模型。
原始数据类型：
format
Comments
原始数据类型有一个可选的属性 format，用于指定具体的数据类型，可以是任意字符串，比如 email 或 uuid。
对于参数对象或响应对象来说，还有 file 类型，表示参数或响应是一个文件。
Schema
Swagger Object
Swagger 对象是文档一些的根对象。
title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: http://swagger.io/terms/
contact:
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
联系信息。
Field Name
Description
Required
description: Returns all pets from the system that the user has access to
produces:
- application/json
responses:
'200':
description: A list of pets.
schema:
type: array
items:
$ref: '#/definitions/pet'
Path Item Object
定义路径支持的操作（HTTP 方法）。
Field Pattern
Description
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- application/xml
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
type: string
- 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:
'200':
description: Pet updated.
'405':
description: Invalid input
security:
- petstore_auth:
- write:pets
- read:pets
External Documentation Object
引用外部资源来扩展文档
Field Name
Description
描述接口参数。
参数的唯一性由 name 和 location 定义。
location 指明参数的位置，可以是 path, query, Header, body, formData。
关于 body：
只允许有一个 body
body 的名称没有实际用途，只是用于文档描述
body 和 form 不能同时存在
string
参数类型。该值【必须】是 "string", "number", "integer", "boolean", "array", "file"。如果类型是 "file"， 则 consumer 【必须】是 "multipart/form-data", " application/x-www-form-urlencoded"；in 【必须】是 "formData"。
format
string
具体参数类型
allowEmptyValue
boolean
是否允许空值。只有 in 是 query 或 formData 才会生效。如果允许，可以只传参数名或传空值。默认是 false。
items
Items Object
描述数组元素的类型
当 type 是 array 时必填
collectionFormat
string
数组格式。可选择是：csv，逗号分隔。ssv：空格分隔。tsv：反斜杠分隔。pipes：管道分隔。multi：。默认是 csv。
default
参数默认值
maximum
number
schema
Schema Object
响应结构定义。该值可以是原始类型，数组或对象。如果没有指定该属性，则意味着该响应没有内容。如果它的 "type" 是 "file"，则【应该】同时声明 produces 的 MIME 类型。
headers
Headers Object
响应头列表
examples
Example Object
响应消息示例
响应是一个复杂类型数组：
description: A complex object array response
schema:
type: array
items:
$ref: '#/definitions/VeryComplexType'
响应是字符串：
description: A simple string response
schema:
type: string
响应中包含一些响应头：
description: A simple string response
schema:
type: string
headers:
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
type: integer
X-Rate-Limit-Reset:
description: The number of seconds left in the current period
type: integer
响应没有响应内容：
description: object created
响应的头对象列表。
Field Pattern
Description
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
type: integer
X-Rate-Limit-Reset:
description: The number of seconds left in the current period
type: integer
Example Object
响应的示例。
Field Pattern
Description
