如何编写基于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/#
- ``
YAML swagger: "2.0" info: description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key \
special-key` to test the authorization filters."
version: "1.0.0"
title: "Swagger Petstore"
termsOfService: "http://swagger.io/terms/"
contact:
email: "[email protected]"
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"
- name: "pet"
从零开始
-
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、主机名、根路径来描述:
YAML 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