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）

定义（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定义了如下格式

模式（Schema）

Swagger 对象（Swagger Object）

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

固定字段（Fixed Fields）

通配对象（Patterned Objects）

Info对象（Info Object）

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

固定字段（Fixed Fields）

通配对象（Patterned Objects）

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": "support@swagger.io"
  },
  "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: support@swagger.io
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）

通配对象（Patterned Objects）

Contact 对象示例:

{
  "name": "API Support",
  "url": "http://www.swagger.io/support",
  "email": "support@swagger.io"
}

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

许可证对象（License Object）

公开API的许可信息。

固定字段（Fixed Fields）

通配对象（Patterned Objects）

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）

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）

通配对象（Patterned Objects）

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）

通配对象（Patterned Objects）

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）

通配对象（Patterned Objects）

外部文档对象示例：

{
  "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）

通配对象（Patterned Objects）

固定字段（Fixed Fields）

通配对象（Patterned Objects）

固定字段（Fixed Fields）

通配对象（Patterned Objects）

固定字段（Fixed Fields）

通配对象（Patterned Objects）

固定字段（Fixed Fields）

通配对象（Patterned Objects）

Previousinfo Next附录*能愿动词

Last updated 5 years ago