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