Swagger2.0结构说明

元数据

1.每个Swagger规范都以Swagger版本开始

swagger: "2.0"

2.需要指定API的info-title,description（可选）,version（API版本,不是文件版本/Swagger版本）

info:
title: Instruction API
description:this is the API's description
version:1.0.0

• version 可以是自定义字符串，eg:1.0-beta,2018-02-02等
• description 可以使多行的
• info 中也可以支持其他信息对象，例如license, contact等

API调用的基础URL

所有API调用的基础URL由host , schemes , basePath（根级别）组成

 host: api.instruction.com
basePath: /example
schemes:
- https

基础路径的设置已经完成，若是加上端点/users就可以形成完整的路径了：
<scheme>://<host>/<basePath>/users

路径

API路径paths和操作在API规范的全局部分定义，GET /用户可以用以下来描述：

paths:
/users:
get:
summary:Returns a list of users.
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK

可以理解为是相对路径，完整路径如下：
scheme://host/basePath/path

• 支持路径模版：
  意味着您可以使用花括号{}将URL的部分标记为路径参数：

paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: Parameter description in Markdown.
responses:
200:
description: OK

eg: /users/1

Consumes和Produces定义

• consumes：指定处理请求的提交内容类型（Content-Type）
• produces：指定返回的内容类型，仅当request请求头中的（Accept）中包含指定类型才可以

consumes:
- application/json
- application/xml
produces:
- application/json
- application/xml

• 这里的类型均为MIME类型
• consumes只影响与POST，PUT和PATCH等请求主体的操作。对于像GET这样的无人机操作，它会被忽略

响应

对于每个操作，可以定义可能的状态代码，以及schema响应主体。schema可以通过内联定义或从外部定义引用$ref(如果多个响应使用相同的模式，可以在根级定义并通过引用$ref)。还可以为不同的内容类型提供示例响应

 paths:
/users/{userId}:
get:
summary: 根据用户ID返回一个对象 user.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: 根据ID返回对象
responses:
200:
description: User成功获取
schema:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: BlingBlingY
400:
description:输入值不合法，不是数字.
schema:
$ref: "#/definitions/User"
404:
description: 不存在该用户.
default:
description: 未知错误
definitions:
User:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.

输入和输出模型

全局的definitions允许定义通用数据结构。任何时候无论是request还是response,schema里需要用到，都可以通过$ref 来引用它们
例如：

{
"id": 4,
"name": "Arthur Dent"
}

可以表示为：

 definitions:
User:
properties:
id:
type: integer
name:
type: string
# Both properties are required
required:
- id
- name

在请求主体模式和响应主体模式中引用:

paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
responses:
200:
description: OK
schema:
$ref: '#/definitions/User'
/users:
post:
summary: Creates a new user.
parameters:
- in: body
name: user
schema:
$ref: '#/definitions/User'
responses:
200:
description: OK

认证

在API中使用的身份验证关键词：securityDefinitions和security

securityDefinitions:
BasicAuth:
type: basic
security:
- BasicAuth: []

1. 目前API支持的三种认证方法：

• 基本认证 - BasicAuth
• API密钥 - ApiKey
• OAuth2 公共流程

2. securityDefinitions来定义该API支持的所有身份验证类型

securityDefinitions:
BasicAuth:
type: basic
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl:
https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read: Grants read access
write: Grants write access
admin: Grants read and write access to administrative information

在定义了安全机制后securityDefinitions，您可以security分别在根级别或操作级别上添加该部分，将它们应用于整个API或单个操作。

在根级别上使用时，security将指定的安全机制全局应用于所有API操作，除非在操作级别上被覆盖。在以下示例中，可以使用API​​密钥或OAuth 2对API调用进行身份验证.ApiKeyAuth和OAuth2名称是指上文定义过的安全机制securityDefinitions

security:
- ApiKeyAuth: []
- OAuth2: [read, write]

全局security可以在个别操作中被覆盖，从而可以使用不同的认证类型，有的根本不认证，如下例：

paths:
/billing_info:
get:
summary: Gets the account billing info
security:
- OAuth2: [admin]
# Use OAuth with a different scope
responses:
200:
description: OK
401:
description: Not authenticated
403:
description: Access token does not have the required scope
/ping:
get:
summary: Checks if the server is running
security: []
# No security
responses:
200:
description: Server is up and running
default:
description: Something is wrong

3. 多种验证类型
   security模块可使用逻辑OR和AND组合安全要求，来实现所需的结果

security:
# A OR B
- A
- B
security:
# A AND B
- A
B
security:
# (A AND B) OR (C AND D)
- A
B
- C
D

• 使用基本身份验证或API密钥：

security:
- basicAuth: []
- apiKey: []
security:
- apiKey1: []
apiKey2: []

• API需要在请求中包含一对API密钥：

security:
- apiKey1: []
apiKey2: []

• 使用OAuth 2或一对API密钥：

security:
- oauth2: [scope1, scope2]
- apiKey1: []
apiKey2: []

参考资料：
https://swagger.io/docs/specification/about/

作者：小菜鸟_Sonya
链接：https://www.jianshu.com/p/c22bf8e173a1
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

最后

以上就是留胡子缘分为你收集整理的Swagger2.0结构说明Swagger2.0结构说明的全部内容，希望文章能够帮你解决Swagger2.0结构说明Swagger2.0结构说明所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。