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 7231IANA Status Code Registry

规范

格式

遵从 Swagger 规范的 API 文档可以是一个 JSON 或 YAML 格式的文件。

所有属性名都是大小写敏感的。

文件结构

API 文档是一个单一的文件,但部分定义可以被拆分到不同文件。

通常 API 文档被命名为 swagger.jsonswagger.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,用于指定具体的数据类型,可以是任意字符串,比如 emailuuid

对于参数对象或响应对象来说,还有 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'
posted @ 2022-07-01 22:05  廖子博  阅读(3316)  评论(0编辑  收藏  举报