OpenApi 规范（OpenApi Spec）

原文：OpenApi Spec 翻译：小虾米（QQ:509129）

参考：OpenAPI Specification 2.0

OpenApi 规范（OpenApi Spec）

fka Swagger RESTful API 文档规范

版本2.0（Version 2.0）

文中所使用到的”MUST”,”MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”和”OPTIONAL”均遵循RFC 2119定义。

Swagger 规范是根据 The Apache License, Version 2.0.

介绍（Introductions）

Swagger™ 是一个用于描述文档的RESTful API项目。

Swagger 规范定义了描述这种API所需的一组文件。这些文件可以 Swagger-UI 项目用来显示API和Swagger的代码生成生成各种语言的客户。额外的实用程序也可以利用生成的文件，例如测试工具。

修订历史（Revision History）

版本（Version）	日期（Date）	说明（Notes）
2.0	2014-09-08	发布 Swagger 2.0
1.2	2014-03-14	正式文件的初步发布。
1.1	2012-08-22	发布 Swagger 1.1
1.0	2011-08-10	首次发布 Swagger 规格

定义（Definitions）

路径模板（Path Templating）

路径模板是指使用大括号 ({}) 来标记URL路径的一部分，使用路径参数作为可替换的参数。

MIME类型（Mime Types）

MIME类型定义在多个资源中传播。MIME类型定义应符合RFC 6838。

可能MIME类型定义的一些示例：

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP状态码（HTTP Status Codes）

HTTP状态码用于指示执行的操作的状态。RFC 7231和IANA状态代码注册表中描述了可用的状态代码。

规范（Specification）

格式（Format）

根据Swagger的规范描述RESTful API的文件被表示为JSON对象，并符合JSON标准。YAML作为JSON的超集，也可以用来表示一个Swagger的规范文件。

例如，如果字段被认为具有数组值，那么将使用JSON数组表示:

{
   "field" : [...]
}

当使用JSON描述API时，它不会将JSON输入/输出强加给API本身。

规范中的所有字段名称都是大小写敏感的。

该模式公开了两种类型的字段(fields)。

• 第一种是fixed fields，是说field的名称是固定的；

• 第二种是Patterned fields，field的名字不是固定的，而是使用正则表达式匹配。

文件结构(File Structure)

Swagger的规范要求将API用一个单一的文件表示。不过，根据用户的判断，部分定义可以拆成多个文件。使用 $ref 将他们拼合在一起。这符合JSON Schema规范。

按照惯例，Swagger规范文件命名为 swagger.json。

数据类型（Data Types）

Swagger 规范中的原始数据类型基于JSON-Schema Draft 4所支持的类型。使用模式对象描述模型，该对象是JSON Schema Draft 4的子集。

另外一个原始数据类型“file”，用于在参数对象或者响应对象中设置参数类型或者响应为一个文件

原始类型有一个可选的属性format，Swagger使用了集中常见的格式来对数据类型做更细微的定义。然而，format属性是一个开放式的string类型的数据，可以填写任何支持的属性。格式可以是email、uuid，甚至可以是一些没有在规范中支持的属性。格式和数据类型并不一定要一致（文件除外），Swagger定义了如下格式

名称（Common Name）	类型（type）	format	说明
integer	integer	int32	signed 32 bits
long	integer	int64	signed 64 bits
float	number	float
double	number	double
string	string
byte	string	byte	base64 encoded characters
binary	string	binary	any sequence of octets
boolean	boolean
date	string	date	As defined by full-date - RFC3339
dateTime	string	date-time	As defined by date-time - RFC3339
password	string	password	Used to hint UIs the input needs to be obscured.

模式（Schema）

Swagger 对象（Swagger Object）

这是API规范的根文档对象。它将以前的资源清单和API声明(版本1.2和早期)合并到一个文档中。

固定字段（Fixed Fields）

字段名称（Field Name）	类型（Type）	描述（Description）
swagger	string	必需的。指定使用的Swagger 规范版本。它可以Swagger UI和其他客户使用来解释API清单。该值必须是“2.0”。
info	Info对象（Info Object）	必需的。提供关于API的元数据。如果需要的话，客户端可以使用元数据。
host	string	服务于API的主机(域名或ip)。这必须是主机，不包括scheme和子路径。它可能包括一个端口。如果不包括主机，则将使用该文档的主机(包括端口)。主机不支持路径模板。
basePath	string	提供API的基本路径，它是相对于主机的。如果不包括它，则API直接服务于主机。值必须以一个斜杠(/)开始。basePath不支持路径模板。
schemes	string数组（[string]）	定义API传输的协议。值必须来自列:“http”、“https”、“ws”、“wss”。如果不包指定schemes，默认的scheme就是访问Swagger时访问的协议。
consumes	string数组（[string]）	api可以使用的MIME类型列表。这对所有API都是全局的，但是可以在特定的API调用上重写。值必须按照Mime类型所描述的那样。
produces	string数组（[string]）	API可生成的MIME类型列表。这对于所有API都是全局的，但可以在特定的API调用上重写。价值必须像Mime Types所描述的那样。
paths	Paths对象（Paths Object）	必需的。API的可用路径和操作符。
definitions	Definitions对象（Definitions Object）	一个对象，用来保存由操作生成和使用的数据类型。
parameters	Parameters Definitions 对象	可以在整个操作中使用参数的对象。此属性不为所有操作定义全局参数。
responses	Responses Definitions 对象	可以在整个操作中使用响应的对象。该属性不定义所有操作的全局响应。
securityDefinitions	Security Definitions 对象	可以跨规范使用的安全性方案定义。
security	Security Requirement 对象数组	将API应用于整个安全计划的声明。值的列表描述可使用的其他安全方案（也就是说，有一个逻辑或在安全要求之间）。个别操作可以重写这个定义。
tags	Tag 对象数组	该规范使用附加元数据的标签列表。标签的顺序可以用来反映他们的秩序的分析工具。并非所有由操作对象使用的标签都必须声明。未声明的标签可以随机组织或基于工具的逻辑。列表中的每个标记名称必须是唯一的。
externalDocs	External Documentation 对象	添加外部文件。

通配对象（Patterned Objects）

Field Pattern	Type	Description
^x-	任何类型（Any）	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

Info对象（Info Object）

该对象提供关于API的元数据。如果需要的话，客户端可以使用元数据，并且可以在Swagger-UI中提供方便。

固定字段（Fixed Fields）

Field Name	Type	Description
title	string	必需的。应用程序的标题。
description	string	对应用程序的简短描述。GFM语法可用于富文本表示。
termsOfService	string	API的服务条款。
contact	Contact Object	API作者联系方式。
license	License Object	API的许可证信息。
version	string	必需的。提供应用程序API的版本(不要与规范版本混淆)。

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

Info 对象示例:

{
  "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": "[e-mail]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

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: [e-mail]
license:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

Contact 对象（Contact Object）

API的作者联系信息。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）
name	string	联系人/组织的识别名称。
url	string	指向联系人信息的URL。必须以URL的格式。
email	string	联系人/组织的电子邮件地址。必须以电子邮件地址的格式。

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

Contact 对象示例:

{
  "name": "API Support",
  "url": "http://www.swagger.io/support",
  "email": "[e-mail]"
}

name: API Support
url: http://www.swagger.io/support
email: [e-mail]

许可证对象（License Object）

公开API的许可信息。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）
name	string	必需的。用于API的许可证名称。
url	string	用于API的许可证的URL。必须以URL的格式。

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

License 对象示例:

{
  "name": "Apache 2.0",
  "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}

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

Paths 对象(Paths Object)

用于保存各个接口的相对路径。加上basePath就可以组成完整的URL了。Paths可以为空，详见ACL constraints。

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
/{path}	Path Item 对象	单个接口的相对路径。字段名必须以斜线开始。路径被追加到basePath以构造完整的URL。允许使用路径模板。
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

Paths 对象示例：

{
  "/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"
            }
          }
        }
      }
    }
  }
}

/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 对象（Path Item Object）

用于描述对于单一Path可以进行的操作。Path Item可以为空，这种情况下，路径仍然会暴露在文档查看器，但是用户并不知道可以进行哪些操作和参数。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）
$ref	string	允许从外部引入一个配置。被引用的结构必须符合Path Item对象的结构。如果说引用于当前项配置冲突，则behavior为undifined
get	Operation 对象	此路径上的GET操作定义
put	Operation 对象	此路径上的POST操作定义
post	Operation 对象	此路径上的PUT操作定义
delete	Operation 对象	此路径上的DELETE操作定义
options	Operation 对象	此路径上的OPTIONS操作定义
head	Operation 对象	此路径上的HEAD操作定义
patch	Operation 对象	此路径上的PATCH操作定义
parameters	[Parameter 对象数组 | Reference 对象数组]	适用于此路径下描述的所有操作的参数列表。这些参数可以在操作级别重写，但不能在那里删除。列表必须不包含重复的参数。一个惟一的参数由名称和位置的组合来定义。该列表可以使用引用对象来链接到Swagger对象的参数中定义的参数。最多可以有一个“body”参数。

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

Path Item 对象示例

{
  "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"
    }
  ]
}

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 对象（Operation Object）

描述路径上的一个API操作。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）
tags	[string]
summary	string
description	string
externalDocs	外部文档对象
operationId	string
consumes	[string]
produces	[string]
parameters	[Parameter 对象数组 | Reference 对象数组]
responses	Responses 对象
schemes	[string]
deprecated	boolean
security	[Security Requirement 对象数组]

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

Operation 对象示例：

{
  "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"
      ]
    }
  ]
}

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）

允许引用外部资源来扩展文档。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）urlurl
description	string	目标文档的简要描述。可以使用GFM语法。
url	string	必须的。目标文档的URL。必须符合URL格式。

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

外部文档对象示例：

{
  "description": "Find more info here",
  "url": "https://swagger.io"
}

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

Parameter 对象（Parameter Object）

描述单个操作参数。

唯一的参数由name和location的组合定义。

有五种可能的参数类型。

• Path - 与路径模板一起使用，其中参数值实际上是操作的URL的一部分。这并不包括API的主机或基本路径。例如，在 /items/{itemId} 中，路径参数是itemId。

• Query - 添加到URL的参数。例如,在 /items?id=###，查询参数是id。

• Header - 自定义的请求头参数，作为请求的一部分。

• Body - 附加到HTTP请求的payload。因为只有一个payload，所以只能有一个Body参数。body参数的名称对参数本身没有影响，仅用于文档目的。考虑到Form本身也是一种Body，所以对于同一个操作，Form和Body不能共存。

• Form - 当请求的contentType为application/x-www-form-urlencoded或者application/form-data或者两者都有时(在Swagger的定义中，操作的consumes属性)。用于描述附加在HTTP请求上的payload。这是唯一可以用来发送文件的参数类型，从而支持文件类型。由于在payload中发送了表单参数，因此无法将它们与相同操作的body参数一起声明。表单参数的格式与使用的内容类型有不同(为了进一步的细节，请参考http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):

application/x-www-form-urlencoded- 与Query参数格式相似，但是却是一个payload。例如：

foo=1

&

bar=swagger

中，foo和bar都是表单参数。这种格式通常用于简单参数的传输。

multipart/form-data- 每个参数使用一个内部的header单独占一段。例如：

Content-Disposition: form-data; name="submit-name"

，参数的名字是

submit-name

。这种类型的表单多用于文件传输。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。

固定字段（Fixed Fields）

字段名（Field Name）	类型（Type）	描述（Description）

通配对象（Patterned Objects）

字段通配（Field Pattern）	类型（Type）	描述（Description）
^x-	Any	Swagger约束所允许的拓展。成员名必须以x-开头，例如，x-internal-id。值可以为null、原始类型或者是一个数组或者一个对象。。有关进一步的详细信息，请参阅Vendor扩展。