The Best APIs are Built with Swagger Tools
Swagger分为四部分：
swagger: “2.0”
info:
version:1.0.0
title:simple api
description:a simple api to learn how to write openAPI specification
schemes:
-https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
1.openApi规范的版本号
通过一个 swagger 属性来声明OpenAPI规范的版本。
swagger: “2.0”
2.Api描述信息：
文档相关信息
info:
version:1.0.0
title:simple api
description:a simple api to learn how to write openAPI specification
3.API的URL
作为web API，一个很重要的信息就是用来给消费者使用的 根URL ，可以用协议
（http或者https）、主机名、根路径来描述：
schemes:
-https
host: simple.api
basePath: /openapi101
4.API的操作
4.1添加一个 路径
paths:
/persons:
4.2在路径中添加一个HTTP方法
比如需要展示一组用户信息，我们可以在 /persons 路径中添加 get 方法，同时
还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论
（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
4.3定义 响应 （response）类型
对于每个方法（或操作），我们都可以在 响应 (responses)中添加任意的HTTP状
态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上 200 的响
应：
responses:
200:
description: A list of Person
4.4定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的 模
式 （schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的 数组 （array），每一个数组元素则是一个
用户信息 对象 （object），该对象包含三个string类型的属性： 姓氏 、 名
字 、 用户名 ，其中 用户名 必须提供（required）。
schema:
type:array
items:
required:
-username
properties:
firstName:
type:string
lastName:
type:string
username:
type:string
4.5定义 请求参数 （query parameters）
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
4.5.1在get方法中增加请求参数
parameters:
4.5.2添加分页参数
在参数列表中，我们添加两个名字（name）分别叫
做 pageSize 和 pageNumber 的整型（integer）参数，并作简单描述：
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer