如何编写基于OpenAPI规范的API文档
简介
Swagger
Swagger是一个简单但功能强大的API表达工具。支持的语言种类繁多
使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性
OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图定义一种用来描述API格式或API定义的语言，来规范RESTful服务的开发过程
OpenAPI可以帮助我们描述一个API的基本信息：
有关API的一般性描述
可用路径
在每个路径上的可用操作
每个操作的输入输出格式
OpenAPI规范这类API定义语言能够更简单、快速的表述API，尤其是在API设计阶段作用比较明显
如何编写API文档
编辑器采用在线编辑：https://editor.swagger.io/
swagger: "2.0"
info:
description:
version: "1.0.0"
title: "Swagger Petstore"
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"
basePath: "/v2"
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"
schemes:
- "http"
paths:
/pet:
post:
tags:
- "pet"
summary: "Add a new pet to the store"
description: ""
operationId: "addPet"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Pet object that needs to be added to the store"
required: true
schema:
$ref: "#/definitions/Pet"
responses:
405:
description: "Invalid input"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
从零开始
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
{}
显示界面如下：
首先要通过swagger属性来声明OpenAPI规范的版本
然后需要说明API文档的相关信息，比如API文档版本、API文档名称、描述信息等
最后作为webURL，一个很重要的信息就是用来给消费者使用的 根URL ，可以使用协议http或https、主机名、根路径来描述：
schemes:
- https
host: simple.api
basePath: /openapi101
```
接下来就是写API的操作，通过paths，然而这里没有写只是通过{}对象占用位置
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Get 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
在上面的这些代码中，做了以下的动作：
添加了/persons的路径，用来访问一组用户信息
在路径中添加了HTTP方法get，同时也有一些简单的描述信息summary和description
定义响应类型responses，响应类型中添加了HTTP状态码200
定义了响应内容：通过响应消息中的schema属性来描述清楚具体的返回内容。通过type属性可知一组用户信息就是一个用户信息数组，每一个数组元素则是一个用户对象，该对象包含三个string类型的属性，其中username必须提供（required）
定义请求参数
paths:
/persons:
get:
summary: Get some persons
description: Returns a list containing all persons
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
首先在get方法中添加了一个parameters属性
在参数列表中，添加了两个参数pageSize和pageNumber的整形参数，并有简单描述
定义路径参数
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons/{username}:
get:
summary: Get some persons
description: Returns a list containing all persons
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
路径参数、请求参数以及消息参数等的不同之处就在于in属性的值不同，分别为path、query、body等。同时对于参数的类型可以使用type或者schema来定义，例如消息体参数如下：
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
post:
summary: Creates a person
description: Adds a new person to the persons list
parameters:
- name: person
in: body
description: The person to create
schema:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
responses:
200:
description: OK
如果是单个参数可以使用type进行定义例如integer，string ，array等，而如果是json类型的参数就需要使用schema类来定义。
定义相应消息
response:
204:
description:Persons successfully created
400:
description:Persons couldn't have been created
简化数据模型
通过使用definition来定义可重用的对象。如下：
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
post:
summary: Creates a person
description: Adds a new person to the persons list
parameters:
- name: person
in: body
description: The person to create
schema:
$ref: '#/definitions/Person'
responses:
200:
description: OK
schema:
$ref: "#/definitions/Person"
definitions:
Person:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
定义可重用的参数
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons/{username}:
get:
parameters:
- $ref: '#/parameters/username'
responses:
200:
description: fsafsf
parameters:
username:
name: username
in: path
required: true
description: The person's username
type: string
高级定义
字符串的长度和格式
- name: username
in: path
required: true
description: fasfsa
type: string
pattern: "[a-z0-9]{8,64}"
minLength: 8
maxLength: 64
日期和时间
parameters:
- name: dateofBirth
in: query
description: fasfsaf
type: string
format: date
枚举类型
code:
type: string
enum:
- DBERR
- NTERR
- UNERR
高级参数
参数的媒体类型
在文档的根节点下面添加：
produces:
- text/xml
consumes:
- application/json
- application/xml
高级响应消息
要定义一个不带消息体的相应消息，只需要写响应状态和描述即可
responses:
'204':
description: Person successfully created
与请求消息类似，必带参数使用required来标识
Person:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
分类标签
tags: – Persons
