Swagger2.0结构说明_综合

Swagger2.0结构说明

元数据

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

swagger: "2.0"

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

info:title: Instruction APIdescription:this is the API's descriptionversion: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.combasePath: /exampleschemes: - 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/jsonresponses:200:description: OK

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

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

paths:/users/{
    userId}:get:summary: Returns a user by ID.parameters:- in: pathname: userIdrequired: truetype: integerminimum: 1description: 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可以通过内联定义或从外部定义引用 $r e f (如果多个响应使用相同的模式，可以在根级定义并通过引用$ ref)。还可以为不同的内容类型提供示例响应

 paths:/users/{
    userId}:get:summary: 根据用户ID返回一个对象 user.parameters:- in: pathname: userIdrequired: truetype: integerminimum: 1description: 根据ID返回对象responses:200:description: User成功获取schema:type: objectproperties:id:type: integerexample: 1name:type: stringexample: BlingBlingY400:description:输入值不合法，不是数字.schema:$ref: "#/definitions/User"404:description: 不存在该用户.default:description: 未知错误
definitions:User:type: objectproperties:id:type: integerdescription: The user ID.username:type: stringdescription: The user name.

输入和输出模型

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

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

可以表示为：

 definitions:User:properties:id:type: integername:type: string# Both properties are requiredrequired:  - id- name

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

paths:/users/{
    userId}:get:summary: Returns a user by ID.parameters:- in: pathname: userIdrequired: truetype: integerresponses:200:description: OKschema:$ref: '#/definitions/User'/users:post:summary: Creates a new user.parameters:- in: bodyname: userschema:$ref: '#/definitions/User'responses:200:description: OK

认证

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

securityDefinitions:BasicAuth:type: basicsecurity:- BasicAuth: []

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

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

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

securityDefinitions:BasicAuth:type: basicApiKeyAuth:type: apiKeyin: headername: X-API-KeyOAuth2:type: oauth2flow: accessCodeauthorizationUrl:     https://example.com/oauth/authorizetokenUrl: https://example.com/oauth/tokenscopes:read: Grants read accesswrite: Grants write accessadmin: 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 infosecurity:- OAuth2: [admin]   # Use OAuth with a different scoperesponses:200:description: OK401:description: Not authenticated403:description: Access token does not have the required scope/ping:get:summary: Checks if the server is runningsecurity: []   # No securityresponses:200:description: Server is up and runningdefault:description: Something is wrong

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

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

使用基本身份验证或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
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。