定义

版本 3.0.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

This document is licensed under The Apache License, Version 2.0.

介绍

OpenAPI 规范(OAS),是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好,那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API,那么您就可以用文档生成工具来展示您的 API,用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码,用自动测试工具进行测试等等。

目录

术语定义

开放API文档

一(或多)份用来定义或描述一个API的文档。

路径模板

路径模板指用大括号标记来标记一段URL作为可替换的路径参数。

媒体类型

媒体类型定义分散于多处。 媒体类型定义应当符合RFC6838

以下是一些媒体类型定义的示例:

  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状态码被用来表示一次请求的被执行状态。 RFC7231定义了有效的状态码,可以在IANA Status Code Registry找到已经被注册的状态码的列表。

规范

版本

开放API规范使用符合语义化版本 2.0.0(semver)规范的版本号。

语义化版本的主版本号次版本号部分(比如3.0)应当被用来标记开放API规范的特性变动。通常 .修订号 版本被用来表示本文档文档的错误修正而不是特性变动。支持开放API规范3.0的工具应该兼容所有3.0.*的版本,工具不应当关注修订版本号,比如3.0.03.0.1对它来说应该没有任何区别。

此后开放API规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此3.1.0版本的规范应当可以在面向3.0.0版本规范开发的工具内使用。

任何兼容开放API规范 3.*.* 的文档应当包含一个openapi 字段用来表明它使用的规范的语义化版本。

格式

一份遵从开放API规范的文档是一个自包含的JSON对象,可以使用JSON或YAML格式编写。

比如一个字段有一组值,用JSON格式表示为:

{
   "field": [ 1, 2, 3 ]
}

规范内的所有字段名都是小写

字段分为两种:固定字段和模式字段。固定字段的字段名是确定的,模式字段的字段名需要符合一定的模式。

如果一个对象里有模式字段,那么在这个对象里的模式字段的名字不能有重复的。

为了保留在 YAML 和 JSON 格式之间转换的能力,推荐使用1.2版本的YAML格式,而且还需要符合以下限制:

注意: 虽然API文档是使用 YAML 或 JSON 格式书写的,但是API的请求体和响应体或者其他内容可以是任何格式。

文档结构

一份 OpenAPI 文档可以是单个文件也可以被拆分为多个文件, 连接的部分由用户自行决定。在后一种情形下,必须如 JSON Schema 中定义的那样使用 $ref 字段来相互引用。

推荐将根开放API文档命名为openapi.jsonopenapi.yaml

数据类型

在 OAS 中的原始数据类型是基于 JSON Schema Specification Wright Draft 00 所支持的类型。注意 integer 也作为一个被支持的类型并被定义为不包含小数或指数部分的 JSON 数字。 null 不是一个被支持的类型 (查看 nullable 来获得替代解决方案)。 Models 使用 Schema Object 定义,这是一个 JSON Schema Specification Wright Draft 00 的扩展。

原始类型可以有一个可选的修饰属性:format。 OAS 使用多个已知的格式来丰富类型定义。尽管如此,为了文档的需要,format 属性被设计为一个 string 类型的开放属性值,可以包含任意值。比如 "email", "uuid" 等未被此规范定义的格式也可以被使用。没有被定义的 format 属性类型遵从 JSON Schema 中的类型定义。无法识别某个 format 值的工具应该回退到 type 值,就像 format 未被指定一样。

被 OAS 定义的格式:

通用名

备注

integer

integer

int32

32 位有符号

long

integer

int64

64 位有符号

float

number

float

double

number

double

string

string

byte

string

byte

base64 编码的支付

binary

string

binary

任意 8进制序列

boolean

boolean

date

string

date

定义于 full-date - RFC3339

dateTime

string

date-time

定义于 date-time - RFC3339

password

string

password

告知输入界面不应该明文显示输入信息。

富文本格式

整个规范中的 description 字段被标记为支持 CommonMark markdown 格式。 OpenAPI 相关的工具在支持 CommonMark 0.27 中描述的富文本格式方面至少需要支持渲染 markerdown。相关工具为了安全考虑可以选择忽略某些 CommonMark 特性。

URL的相对引用

除非明确指定,所有 URL 类型的属性值都可以是相对地址,就如 RFC3986 中定义的那样以 Server Object 作为 Base URI。

$ref 中的相对引用以 JSON Reference 为依据,以当前文档的 URL 作为 base URI. 同时参考 Reference Object

结构

在接下来的叙述中,如果一个字段没有被明确的标记为 必选 或者被描述为 必须应当,那么可以认为它是一个 可选 字段

OpenAPI 对象

这是OpenAPI document的根文档对象。

固定字段

字段名

类型

描述

openapi

string

必选. 这个字符串必须是开放API规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释开放API文档。这个值和API info.version字符串没有关联。

info

必选。此字段提供API相关的元数据。相关工具可能需要这个字段。

servers

这是一个Server对象的数组, 提供到服务器的连接信息。如果没有提供servers属性或者是一个空数组,那么默认为是url值为/Server 对象

paths

必选。对所提供的API有效的路径和操作。

components

一个包含多种结构的元素。

security

声明API使用的安全机制。The list of values includes alternative security requirement objects that can be used. 认证一个请求时仅允许使用一种安全机制。单独的操作可以覆盖这里的定义。

tags

提供更多元数据的一系列标签,标签的顺序可以被转换工具用来决定API的顺序。不是所有被Operation 对象用到的标签都必须被声明。没有被声明的标签可能被工具按自己的逻辑任意整理,每个标签名都应该是唯一的。

externalDocs

附加的文档。这个对象可能会被规范扩展扩展。

Info 对象

这个对象提供API的元数据。如果客户端需要时可能会用到这些元数据,而且可能会被呈现在编辑工具或者文档生成工具中。

固定字段

字段名

类型

描述

title

string

必选. 应用的名称。

description

string

对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。

termsOfService

string

指向服务条款的URL地址,必须是URL地址格式。

contact

所开放的API的联系人信息。

license

所开放的API的证书信息。

version

string

必选. API文档的版本信息(注意:这个版本和开放API规范版本没有任何关系)。

Info 对象示例

{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}
title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

Contact 对象

所公开的API的联系人信息

固定字段

字段名

类型

描述

name

string

人或组织的名称。

url

string

指向联系人信息的URL地址,必须是URL地址格式。

email

string

人或组织的email地址,必须是email地址格式。

这个对象可能会被规范扩展扩展。

Contact 对象示例

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

License 对象

公开API的证书信息。

固定字段

字段名

类型

描述

name

string

必选. API的证书名。

url

string

指向API所使用的证书的URL地址,必须是URL地址格式。

这个对象可能会被规范扩展扩展。

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

Server 对象

表示一个服务器的对象。

固定字段

字段名

类型

描述

url

string

必选. 指向目标主机的URL地址。这个URL地址支持服务器变量而且可能是相对路径,表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似{brackets}时需要替换此变量。

description

string

一个可选的字符串,用来描述此URL地址。CommonMark syntax可以被用来呈现富文本格式.

variables

一组变量和值的映射,这些值被用来替换服务器URL地址内的模板参数。

这个对象可能会被规范扩展扩展。

Server 对象示例

单个服务器可以这样描述:

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}
url: https://development.gigantic-server.com/v1
description: Development server

以下内容表示的是有多个服务器时应该如何描述,比如OpenAPI 对象的servers

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}
servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

以下内容展示了如何使用变量来配置服务器:

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2

Server Variable 对象

表示可用于服务器URL地址模板变量替换的对象。

固定字段

字段名

类型

描述

enum

[string]

一组可枚举字符串值,当可替换选项只能设置为固定的某些值时使用。

default

string

必选. 当可替换的值没有被使用者指定时使用的默认值。不像Schema Object'sdefault ,这个值必须由使用者提供。

description

string

对服务器变量的可选的描述。CommonMark syntax可以被用来呈现富文本格式.

这个对象可能会被规范扩展扩展。

Components 对象

包含开放API规范固定的各种可重用组件。当没有被其他对象引用时,在这里定义定义的组件不会产生任何效果。

固定字段

字段名

类型

描述

schemas

定义可重用的 Schema 对象 的对象。

responses

定义可重用的 Response 对象 的对象。

parameters

定义可重用的 Parameter 对象 的对象。

examples

定义可重用的 Example 对象 的对象。

requestBodies

定义可重用的 Request Body 对象 的对象。

headers

定义可重用的 Header 对象 的对象。

securitySchemes

定义可重用的 Security Scheme 对象 的对象。

links

定义可重用的 Link 对象 的对象。

callbacks

定义可重用的 Callback 对象 的对象。

这个对象可能会被 规范扩展 扩展。

上面定义的所有固定字段的值都是对象,对象包含的key的命名必须满足正则表达式: ^[a-zA-Z0-9\.\-_]+$

字段名示例:

User
User_1
User_Name
user-name
my.org.User

Components 对象示例

"components": {
  "schemas": {
    "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": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}
components:
  schemas:
    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:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

Paths 对象

定义各个的端点和操作的相对路径。这里指定的路径会和 Server 对象 内指定的URL地址组成完整的URL地址,路径可以为空,这依赖于 ACL constraints 的设置。

模式字段

字段名模式

类型

描述

/{path}

到各个端点的相对路径,路径必须以/打头,这个路径会被直接连接Server 对象url字段以组成完整URL地址(不会考虑是否是相对路径)。这里可以使用 Path templating ,当做URL地址匹配时,不带路径参数的路径会被优先匹配。应该避免定义多个具有相同路径层级但是路径参数名不同的路径,因为他们是等价的。当匹配出现歧义时,由使用的工具自行决定使用那个路径。

这个对象可能会被规范扩展扩展。

路径模板匹配

假设有以下路径,明确定义的路径 /pets/mine 会被优先匹配:

  /pets/{petId}
  /pets/mine

以下路径被认为是等价的而且是无效的:

  /pets/{petId}
  /pets/{name}

以下路径会产生歧义:

  /{entity}/me
  /books/{id}

Paths 对象示例

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}
/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

Path Item 对象

描述对一个路径可执行的有效操作。依赖与 ACL constraints 的设置,一个Path Item可以是一个空对象,文档的读者仍然可以看到这个路径,但是他们将无法了解到对这个路径可用的任何操作和参数。

固定字段

字段名

类型

描述

$ref

string

指定对此路径的外部定义的引用,引用的格式必须符合 Path Item 对象 的格式,如果引用的外部定义和此对象内的其他定义有冲突,该如何处理冲突尚未被定义。

summary

string

一个可选的简要总结字符串,用来描述此路径内包含的所有操作。

description

string

一个可选的详细说明字符串,用于描述此路径包含的所有操作。 CommonMark syntax可以被用来呈现富文本格式.

get

定义适用于此路径的 GET 操作。

put

定义适用于此路径的 PUT 操作。

post

定义适用于此路径的 POST 操作.

delete

定义适用于此路径的 DELETE 操作。

options

定义适用于此路径的 OPTIONS 操作。

head

定义适用于此路径的 HEAD 操作。

patch

定义适用于此路径的 PATCH 操作。

trace

定义适用于此路径的 TRACE 操作。

servers

一个可用于此路径所有操作的替代根server的数组定义。

parameters

一个可用于此路径下所有操作的参数的列表。这些参数可以被具体的操作定义覆盖,但是不能被移除。这个列表禁止包含重复的参数,一个唯一的参数名由 namelocation 的组合来定义。这个列表可以使用 Reference 格式引用定义在 OpenAPI 对象 components/parameters 内的参数。

这个对象可能会被规范扩展扩展。

Path Item 对象示例

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}
get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    style: simple
    items:
      type: string

Operation Object

描述对路径的某个操作。

固定字段

字段名

类型

描述

tags

[string]

用于控制API文档的标签列表,标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。

summary

string

对此操作行为的简短描述。

description

string

对此操作行为的详细解释。CommonMark syntax可以被用来呈现富文本格式.

externalDocs

附加的外部文档。

operationId

string

用于标识此操作的唯一字符串,这个id在此API内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此operationId来唯一的标识一个操作,因此推荐在命名时符合一般的编程命名习惯。

parameters

定义可用于此操作的参数列表,如果一个同名的参数已经存在于 Path Item,那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数,参数的唯一性由 namelocation 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。

requestBody

可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法,在其他没有明确定义的请求方法中,requestBody的消费者应该应该忽略requestBody

responses

必选. 定义执行此操作后的可能的响应值列表。

callbacks

一组相对于父操作的可能出现的回调映射,A map of possible out-of band callbacks related to the parent operation. 映射中的每一个键都唯一的映射一个 Callback 对象, that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.

deprecated

boolean

声明此操作已经被废弃,使用者应该尽量避免使用此操作,默认的值是 false

security

声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象,但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明,因此可以声明一个空数组来变相的移除顶层的安全声明。

servers

一个可用于此操作的额外的 server 数组,这里的定义会覆盖 Path Item 对象 或 顶层的定义。

这个对象可能会被规范扩展扩展。

Operation 对象示例

{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
           "properties": {
              "name": {
                "description": "Updated name of the pet",
                "type": "string"
              },
              "status": {
                "description": "Updated status of the pet",
                "type": "string"
             }
           },
        "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Invalid input",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}
tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Invalid input
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

External Documentation 对象

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

固定字段

字段名

类型

描述

description

string

对引用的外部文档的简短描述。CommonMark syntax可以被用来呈现富文本格式.

url

string

必选. 外部文档的URL地址,这个值必须是URL地址格式。

这个对象可能会被规范扩展扩展。

External Documentation 对象示例

{
  "description": "Find more info here",
  "url": "https://example.com"
}
description: Find more info here
url: https://example.com

Parameter Object

描述一个操作参数。

一个参数的唯一性由 namelocation 的组合来确定。

参数位置

有4种可能的参数位置值可用于in字段:

  • path - 与 Path Templating 一起使用,当参数的值是URL操作路径的一部分时可以使用,但是不包含主机地址或基础路径。比如在路径 /items/{itemId} 中,路径参数是 itemId

  • query - 追加在URL地址之后的参数,比如 /items?id=### 中,查询参数是 id

  • header - 请求中使用的自定义请求头,注意在 RFC7230 中规定,请求头的命名是不区分大小写的。

  • cookie - 用于传递特定的cookie值。

固定字段

字段名

类型

描述

name

string

必选. 参数的名称。参数名是区分大小写

in

string

必选. 参数的位置,可能的值有 "query", "header", "path" 或 "cookie"。

description

string

对此参数的简要描述,这里可以包含使用示例。CommonMark syntax可以被用来呈现富文本格式.

required

boolean

标明此参数是否是必选参数。如果 参数位置 的值是 path,那么这个参数一定是 必选 的因此这里的值必须是true。其他的则视情况而定。此字段的默认值是false

deprecated

boolean

标明一个参数是被弃用的而且应该尽快移除对它的使用。

allowEmptyValue

boolean

设置是否允许传递空参数,这只在参数值为query时有效,默认值是false。如果同时指定了style属性且值为n/a(无法被序列化),那么此字段 allowEmptyValue应该被忽略。

序列化参数的规则有两种。 对于简单的场景, schemastyle 可以用于描述参数的结构和语法。

字段名

类型

描述

style

string

描述根据参数值类型的不同如何序列化参数。默认值为(基于in字段的值):query 对应 formpath 对应 simple; header 对应 simple; cookie 对应 form

explode

boolean

当这个值为true时,参数值类型为arrayobject的参数使用数组内的值或对象的键值对生成带分隔符的参数值。对于其他类型的参数,这个字段没有任何影响。当 styleform时,这里的默认值是 true,对于其他 style 值类型,默认值是false

allowReserved

boolean

决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 :/?#[]@!$&'()*+,;=。 这个属性仅用于in的值是query时,此字段的默认值是false

schema

定义适用于此参数的类型结构。

example

Any

不同媒体类型的示例,示例应该符合响应的结构的编码属性。各个example之间应该是独立的,而且如果一个引用的schema也包含一个示例,那么这里定义的示例应该 覆盖 schema包含的示例。为了展现无法被恰当的用 JSON 或 YAML 格式展现的示例时,可以使用经过必要的编码的字符串值。

examples

不同媒体类型的示例。每个示例应该包含一个对应于指定编码格式的格式正确的值,这个examples映射内包含的对象应该不同于example内的值。而且如果一个引用的schema也包含一个示例,那么这里定义的示例应该 覆盖 schema包含的示例。

对于更复杂的场景,content属性可以定义参数的媒体类型和概要。一个参数必须且只能包含schemacontent属性中的一个。当exampleexamples字段提供了schema对象时,示例必须遵照参数的序列化策略。

字段名

类型

描述

content

Map[string, Media Type Object]

一个定义参数如何呈现的键值对映射。键是媒体类型,值是对应媒体类型的示例数据,此键值对只能包含一组键值对。

样式值

已经定义好了一组style类型用于支持常见的通用的简单参数序列化。

样式

in

描述

matrix

primitive, array, object

path

Path 样式的参数,参见 RFC6570

label

primitive, array, object

path

Label 样式的参数,参见 RFC6570

form

primitive, array, object

query, cookie

Form 样式的参数,参见 RFC6570. 此选项替换定义于OpenAPI 2.0中collectionFormat等于csv (当 explode值为 false)或multi (当 explode值为 true)的情况。

simple

array

path, header

Simple 样式的参数,参见 RFC6570. 此选项替换定义于OpenAPI 2.0 中 collectionFormat等于csv的情况。

spaceDelimited

array

query

空格分隔的数组值。此选项替换定义于OpenAPI 2.0 中 collectionFormat equal to ssv的情况。

pipeDelimited

array

query

管道符`

的数组值。 此选项替换定义于OpenAPI 2.0 中collectionFormatequal topipes`的情况。

deepObject

object

query

提供一种简单的方法来表示参数中的嵌套对象值.

Style 示例

建设一个参数名为color包含如下之一的值:

   string -> "blue"
   array -> ["blue","black","brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

下面这个表展示了各个不同类型值之间的例子。

explode

empty

string

array

object

matrix

false

;color

;color=blue

;color=blue,black,brown

;color=R,100,G,200,B,150

matrix

true

;color

;color=blue

;color=blue;color=black;color=brown

;R=100;G=200;B=150

label

false

.

.blue

.blue.black.brown

.R.100.G.200.B.150

label

true

.

.blue

.blue.black.brown

.R=100.G=200.B=150

form

false

color=

color=blue

color=blue,black,brown

color=R,100,G,200,B,150

form

true

color=

color=blue

color=blue&color=black&color=brown

R=100&G=200&B=150

simple

false

n/a

blue

blue,black,brown

R,100,G,200,B,150

simple

true

n/a

blue

blue,black,brown

R=100,G=200,B=150

spaceDelimited

false

n/a

n/a

blue%20black%20brown

R%20100%20G%20200%20B%20150

pipeDelimited

false

n/a

n/a

blue|black|brown

R|100|G|200

G|150

deepObject

true

n/a

n/a

n/a

color[R]=100&color[G]=200&color[B]=150

这个对象可能会被规范扩展扩展。

Parameter 对象示例

一个值数组,数组元素为64位整数值的请求头参数:

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}
name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

一个值类型为字符串的路径参数:

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}
name: username
in: path
description: username to fetch
required: true
schema:
  type: string

一个值类型为字符串的可选查询参数,允许通过通过重复参数来传递多个值:

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}
name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

一个任意格式的查询参数,允许使用指定类型的未定义参数:

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    },
  },
  "style": "form"
}
in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

使用content定义序列化方法的复杂参数:

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}
in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

Request Body Object

定义请求体。

固定字段

字段名

类型

描述

description

string

对请求体的简要描述,可以包含使用示例,CommonMark syntax可以被用来呈现富文本格式.

content

Map[string, Media Type Object]

必选. 请求体的内容。请求体的属性key是一个媒体类型或者媒体类型范围,值是对应媒体类型的示例数据。对于能匹配多个key的请求,定义更明确的请求会更优先被匹配。比如text/plain会覆盖text/*的定义。

required

boolean

指定请求体是不是应该被包含在请求中,默认值是false

这个对象可能会被规范扩展扩展。

Request Body 示例

一个引用了模型定义的请求体。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example",
            "externalValue": "http://foo.bar/examples/user-example.json"
          }
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "http://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "http://foo.bar/examples/user-example.txt"
        }