Swagger 规范 2.0

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。

数据类型

数据类型可以是原始数据类型或自定义模型。

原始数据类型：

type	format	Comments
integer	int32	32 位有符号整数
integer	int64	64 位有符号整数（long）
number	float
number	double
string
string	byte	base64 编码字符串
string	binary	字节序列
boolean
string	date
string	date-time
string	password	提示 UI 不以明文显示

原始数据类型有一个可选的属性 format，用于指定具体的数据类型，可以是任意字符串，比如 email 或 uuid。

对于参数对象或响应对象来说，还有 file 类型，表示参数或响应是一个文件。

Schema

Swagger Object

Swagger 对象是文档一些的根对象。

Field Name	Type	Description	Required
swagger	string	说明 Swagger 规范版本。可被工具用于解析文档。该值必须是 "2.0"。	必填
info	Info Object	文档元数据。可被工具使用。	必填
host	string	提供 API 服务的主机名或 IP。【必须】是主机名不能包含路径。【可能】包含端口。如果没有指定，默认是文档服务的主机。
basePath	string	API 服务的基础路径。必须以 / 开始。
schemes	[string]	API 服务的传输协议。【必须】是 "http", "https", "ws", "wss"。如果没有指定则与访问文档的协议相同。
consumes	[string]	全局定义可被 API 消费的 MIME 类型。可被具体接口覆盖。
produces	[string]	全局定义 API 返回的 MIME 类型。可被具体接口覆盖。
paths	Paths Object	定义路径及其支持的操作。	必填
definitions	Definitions Object	定义接口使用的数据模型
parameters	Parameters Definitions Object	定义参数使用数据模型
responses	Responses Definitions Object	定义响应使用的数据模型
securityDefinitions	Security Definitions Object
security	[Security Requirement Object]
tags	[Tag Object]	可被文档使用的标签对象列表，提供了一些元数据信息。该列表可被工具用于解析顺序。不必把接口使用的标签都定义在这里。标签对象必须唯一。
externalDocs	External Documentation Object	外部文档

Info Object

定义文档的元数据，这些元数据可被客户端使用。

Field Name	Type	Description	Required
title	string	API 应用的名称	必填
description	string	API 应用的简述
termsOfService	string	提供术语说明的服务
contact	Contact Object	联系信息
license	License Object	API 证书信息
version	string	API 版本。不要和规范版本混淆。	必填

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

Contact Object

联系信息。

Field Name	Type	Description	Required
name	string	个人/组织的名称
url	string	指向联系信息的链接
email	string	联系邮箱

name: API Support
url: http://www.swagger.io/support
email: support@swagger.io

License Object

API 证书信息。

Field Name	Type	Description	Required
name	string	证书名称	必填
url	string	证书链接

name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html

Paths Object

定义 API 路径，该路径会和 basePath 构成完整路径。

Field Pattern	Type	Description
/	Path Item Object	API 路径。路径【必须】以斜杠开始。该路径与 basePath 构成完整路径。

/pets:
  get:
    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	Type	Description
$ref	string	引用已定义的 Path Item Object
get	Operation Object	HTTP 方法
put	Operation Object	HTTP 方法
post	Operation Object	HTTP 方法
delete	Operation Object	HTTP 方法
options	Operation Object	HTTP 方法
head	Operation Object	HTTP 方法
patch	Operation Object	HTTP 方法
parameters	[Parameter Object | Reference Object]	定义该路径下所有操作支持的参数列表，可被具体的操作覆盖。

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  produces:
  - application/json
  - text/html
  responses:
    '200':
      description: pet response
      schema:
        type: array
        items:
          $ref: '#/definitions/Pet'
    default:
      description: error payload
      schema:
        $ref: '#/definitions/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  type: array
  items:
    type: string
  collectionFormat: csv

Operation Object

定义具体的操作（下面将操作描述为接口）。

Field Pattern	Type	Description	Required
tags	[string]	标签列表，可用于逻辑分组。
summary	string	概括接口功能。【应该】少于 120 个字符。
description	string	详细描述接口功能。
externalDocs	External Documentation Object	引用外部文档
operationId	string	接口的唯一标识符，【必须】是全局唯一的。
consumes	[string]	接口消费的 MIME 类型
produces	[string]	接口返回的 MIME 类型
parameters	[Parameter Object | Reference Object]	接口参数列表，可以直接定义 Parameter Object 或者引用 parameters 定义的参数对象。
responses	[Parameter Object | Reference Object]	可能返回响应列表	必填
schemes	[string]	传输协议，"http", "https", "ws", "wss"。
deprecated	boolean	是否过时，默认是 false。
security

tags:
- pet
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	Type	Description
description	string	对外部文档的简短描述
url	string	外部文档链接

description: Find more info here
url: https://swagger.io

Parameter Object

描述接口参数。

参数的唯一性由 name 和 location 定义。
location 指明参数的位置，可以是 path, query, Header, body, formData。

关于 body：

• 只允许有一个 body
• body 的名称没有实际用途，只是用于文档描述
• body 和 form 不能同时存在

Field Name	Type	Description	Required
name	string	参数名。大小写敏感。	必填
in	string	参数位置。可选值是 "query", "header", "path", "formData", "body"。	必填
description	string	参数的简述
required	boolean	参数是否是强制的。对于路径参数，该值是必填的并且【必须】是 true。其他【可能】false。	路径参数必填

如果 in 的值是 body，还有一个属性名：

Field Name	Type	Description	Required
schema	Schema Object	定义 body 的一些属性	必填

body 引用了一个模型定义：

name: user
in: body
description: user to add to the system
required: true
schema:
  $ref: '#/definitions/User'

body 是一个字符串数组：

name: user
in: body
description: user to add to the system
required: true
schema:
  type: array
  items:
    type: string

如果 in 的值不是 body，有一系列属性名来定义参数：

Field Name	Type	Description
type	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
exclusiveMaximum	boolean
minimum	number
exclusiveMinimum	boolean
maxLength	integer
minLength	integer
pattern	string
maxItems	integer
minItems	integer
uniqueItems	boolean
enum	[*]
multipleOf	number

一个 64 位整数数组的 header 参数：

name: token
in: header
description: token to be passed as a header
required: true
type: array
items:
  type: integer
  format: int64
collectionFormat: csv

一个路径参数：

name: username
in: path
description: username to fetch
required: true
type: string

一个可选的查询参数，该参数可以有多个值：

name: id
in: query
description: ID of the object to fetch
required: false
type: array
items:
  type: string
collectionFormat: multi

一个用于文件上传的表单参数：

name: avatar
in: formData
description: The avatar of the user
required: true
type: file

Responses Object

一个保存响应状态码和响应对象的映射关系的容器。
default 映射到所有未显示说明的状态码。
该容器【必须】至少包含一个状态码，并且【应该】是成功的状态码。

Field Name	Type	Description
default	Response Object	Reference Object
	Response Object	Reference Object

'200':
  description: a pet to be returned
  schema:
    $ref: '#/definitions/Pet'
default:
  description: Unexpected error
  schema:
    $ref: '#/definitions/ErrorModel'

Response Object

描述响应对象。

Field Name	Type	Description
description	string	必填。对响应的简述。
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

Headers Object

响应的头对象列表。

Field Pattern	Type	Description
	Header Object	响应头的名称

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	Type	Description
	Any	该属性名【必须】是接口 produces 属性指定的 MIME 值。并且【应该】和实际需要返回的内容一致。

application/json:
  name: Puma
  type: Dog
  color: Black
  gender: Female
  breed: Mixed

Header Object

Field Name	Type	Description
description	string	简述响应头。
type	string	必填。对象类型。【必须】是 "string", "number", "integer", "boolean", "array"。
format	string	类型的进一步描述。
items	Items Object	如果 type 是 array 则必填。描述数组元素类型。
collectionFormat	string	数组格式。
default	*	响应头的默认值。
maximum	number
exclusiveMaximum	boolean
minimum	number
exclusiveMinimum	boolean
maxLength	integer
minLength	integer
pattern	string
maxItems	integer
minItems	integer
uniqueItems	boolean
enum	[*]
multipleOf	number

tag Object

接口标签，为接口添加元数据信息。

Field Name	Type	Description
name	string	必填。标签名。
description	string	简述。
externalDocs	External Documentation Object	外部文档。

name: pet
description: Pets operations

Reference Object

引用 OpenAPI 规范定义的其他对象。
可用于参数对象或响应对应引用，以达到对象复用目的。

Field Name	Type	Description
$ref	string	必填。引用字符串。

引用一个模型对象：

$ref: '#/definitions/Pet'

引用一个定义模型的文件：

$ref: 'Pet.yaml'

引用一个文件中定义的模型：

$ref: 'definitions.yaml#/Pet'

定义对象

一个封装数据类型的对象，该对象可以被接口消费或返回。
这些数据类型可以是原始类型、数组或模型。

Field Pattern	Type	Description
	Schema Object	对象名

Category:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
Tag:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string

Parameters Definitions Object

可以被接口复用的参数对象。

Field Pattern	Type	Description
	Parameter Object	参数对象名

skipParam:
  name: skip
  in: query
  description: number of items to skip
  required: true
  type: integer
  format: int32
limitParam:
  name: limit
  in: query
  description: max records to return
  required: true
  type: integer
  format: int32

Responses Definitions Object

可以被接口复用的响应对象。

Field Pattern	Type	Description
	Response Object	响应对象名。

NotFound:
  description: Entity not found.
IllegalInput:
  description: Illegal input for operation.
GeneralError:
  description: General Error
  schema:
    $ref: '#/definitions/GeneralError'