Swagger 2.0
Swagger规范是REST API的API描述格式,API规范可以用YAML或JSON编写,格式易于学习,并且对人和机器都可读,本文主要基于YAML示例 (json 同理试用),其yaml样本如下:
顶级标签
parameters: # 请求体公共参数定义,使用如下格式引用:
# parameters:
# - $ref: "traffic.yaml#/parameters/get-topfc-request"
responses: # 响应体公共参数定义
# schema:
# - $ref: "traffic.yaml#/parameters/get-topfc-request"
definitions: # 定义对象的公共结构
# schema:
# - $ref: "traffic.yaml#/parameters/get-topfc-request"
元数据
元数据主要包括一些REST 接口的描述信息,包括如下信息:
# “” 或者 ‘’ 都可以表示值,但是“ ” 不进行 特殊字符转义 ,‘’ 进行特殊字符转义
swagger: "2.0" # 每个Swagger规范都以Swagger版本开始。 2.0 表示 swagger 规范版本
info: # 标题信息
description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters." #(此标签可选)
version: "1.0.0" # 表示该rest API版本
title: "Swagger Petstore" #rest api 接口标题名
termsOfService: "http://swagger.io/terms/" #服务条款
contact: # 联系电话
email: "apiteam@swagger.io"
license: #许可证信息
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
基本网址
host: "petstore.swagger.io" # 为API提供服务的主机的域名或IP地址(IPv4)如果与方案的默认端口(对于HTTP为80,对于HTTPS为443)不同,则它可能包含端口号
# 请注意,必须仅是主机域名和IP地址,不可以包含协议名:http(s)://或 其服务端的子路径。
# 如未指定,则假定为提供API 文档所在的主机
# http://api.example.com (x)
# example.com/api/v1 (x)
basePath: "/v2" # 基本网址 必须以"/"开头 相对于主机根目录的所有API路径的URL前缀 不指定默认为"/""
schemes: #请求支持协议 http https wss ws
- "https"
- "http"
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-8OQf7Ozw-1615865552000)(E:\typora\swagger\swagger-基本网址.PNG)]
标签信息
tags: # 标签信息
- name: "pet"
description: "Everything about your Pets"
externalDocs:
description: "Find out more"
url: "http://swagger.io"
- name: "store"
description: "Access to Petstore orders"
- name: "user"
description: "Operations about user"
externalDocs:
description: "Find out more about our store"
url: "http://swagger.io"
媒体类型(MIME TYPE)
API接收和返回的数据媒体类型,如常见的 JSON和XML。可以在根级目录定义定义全局媒体类型,其所有API都会继承( inherite) 。而且每一个API 也可以定义自己的媒体类型,会覆盖根级目录定义的。
consumes: # 定义入参值
- application/json
- application/xml
produces: # 定义返回值,及响应数据
- application/json
- application/xml
#consumes和produces 支持 RFC6838标准 包括如下:
application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain
charset=utf-8
text/html
application/pdf
image/png
# 以及一些特定供应商的MIMETYPE
application/vnd.mycompany.myapp.v2+json
application/vnd.ms-excel
application/vnd.openstreetmap.data+xml
application/vnd.github-issue.text+json
application/vnd.github.v3.diff
image/vnd.djvu
路径与操作
paths 部分定义了API 中路径、端点,及其支持的http 或 wss方法,所有方法都是相对路径。
paths:
/ping: # 必须以"/" 开头 支持模板定义 可以使用大括号{}将URL的一部分标记为路径参数
# /organizations/{orgId}/members/{memberId}
# 操作方式: swagger 2.0 支持 get,post,put,patch,delete,head,options 操作
# 每个路径支持多个操作方式。
# Swagger将路径和操作方式定义为唯一操作。(重点理解)
# 意味着不允许使用同一路径的两个GET或POST方法-即使它们具有不同的参数(参数对唯一性没有影响)
GET /users?firstName=value&lastName=value
GET /users?role=value
# 以上两个url 代表同一个操作,不允许这样定义
#正确的是如下所示:
GET /users/findByName?firstName=value&lastName=value
GET /users/findByRole?role=value
# 路径里面不允许包含查询字符串参数 ,其查询参数应该定义在parameters:结构里
# /users?role={role} (x)
#正确的是如下结构:
/users:
get:
parameters:
- in: query
name: role
type: string
enum: [user, poweruser, admin]
required: false
参数 (parameters)
parameters:
- in: query # "-" 表示列表元素,parameters 是一个list,所以每一个参数都需要携带"-"
# 参数位置 表示该参数位于 api 那个部分 可以有path query body header form
# query: 查询参数,例如/users?role=1&limit=50 只支持基本数据类型,可以是array,但是item必须是基本数据类型
# path: 路径参数,例如/users/{id}
# body: 请求体参数,post put patch 请求主体参数
# header: http 请求头参数,例如X-MyHeader: Value
# formData:表单参数
name: role
type: integer
required: true
description: Numeric ID of the user to get.
- in: query
name: limit
default: 0 # 默认值
minimum: 1 # 最小值
maximum: 100 # 最大值
enum: [1,20,50,100]
type: integer
- in: path # 例如 /users/{id} /cars/{carId}/drivers/{driverId}
#/users/12,34,56 可以是多个值,定义为array
name: id
type: integer
required: true # 路径参数要求必须是true
- in: header # http 请求头参数
name: X-Request-ID
type: string
- in: formData #
name: name
type: string
description: A person's name.
- in: query
name: color
type: array
collectionFormat: csv # arry 转换url后分隔符定义
items:
type: string
enum: [black, white, gray] # 将列表值限定为枚举值
# Path, query, header and form parameters 都可以接受列表参数
GET /users/12,34,56,78 # path url
GET /resource?param=value1,value2,value3 # query url
GET /resource?param=value1¶m=value2¶m=value3 # query url
POST /resource # header
param=value1¶m=value2 #form
collectionFormat
collectionFormat | Description | Example |
---|---|---|
csv (default) |
Comma-separated values. | foo,bar,baz |
ssv |
Space-separated values. | foo bar baz |
tsv |
Tab-separated values. | "foo\tbar\tbaz" |
pipes |
Pipe-separated values. | foo|bar|baz |
multi |
Multiple parameter instances rather than multiple values. This is only supported for the in: query and in: formData parameters. |
foo=value&foo=another_value |
Constant Parameters
您可以将常量参数定义为必需参数,并且只能使用一个可能的值: 参照如下定义:
- in: query
name: version
type: integer
required: true
enum: [0]
# 常数参数与默认参数不同。常量参数始终由客户端发送,而默认值是客户端不发送参数时服务器使用的值。
Parameters Without a Value
查询字符串和表单数据参数只能有一个名称,没有值: 参照如下定义:
GET /foo?metadata
###########################
- in: query
name: metadata
required: true
type: boolean
allowEmptyValue: true # <-----
Common Parameters
同一路径的公共参数
公共参数,和MIME TYPE 一样,全局公共参数可以在path 下定义,则关于该path下的所有operation都可以适应该参数,并且每一个operation 可以覆盖去全局公共参数,也可以添加自己独有的参数。但不可以移除公共参数
paths:
/user/{
id}:
parameters: # 全局公共参数
- in: path
name: id
type: integer
required: true
description: The user ID.
get:
summary: Gets a user by ID.
parameters: # get operation 特有参数
- in: query
name: metadata
type: boolean
required: false
description: If true, the endpoint returns only the user metadata.
responses:
200:
description: OK
patch:
summary: Updates an existing user with the specified ID.
parameters: # patch operation 可以覆盖全局参数
- in: path
name: id
required: true
description: A comma-separated list of user IDs.
type: array
items:
type: integer
collectionFormat: csv
minItems: 1
responses:
200:
description: OK
delete:
summary: Deletes the user with the specified ID.
不同路径的公共参数
可以在全局公共参数里面定义结构,采用$ref 引用该结构
parameters: # 定义公共参数
offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
# Not necessarily the same as the parameter name.
in: query
name: offset
required: false
type: integer
minimum: 0
description: The number of items to skip before starting to collect the result set.
paths:
/users:
get:
summary: Gets a list of users.
parameters:
- $ref: '#/parameters/offsetParam'
responses:
<