ZEROMAKE | keep codeing and thinking!
2018-03-07 | resetful

openapi3 使用

前言

  1. 最近一直在用业余时间写一个个人项目,其中为了学习各种 python 新特性, 使用了各种新技术其中就使用了 openapi3 来描述 api。
  2. 这篇博文就来说明和封装一套生成 openapi 配置。
  3. 这里只讲述 openapi3 的配置结构,并与官方文档统一使用 yaml 格式来说明。
  4. 由于使用 python 代码中的配置与 json 格式相同。
  5. 在阅读此文前请自行了解 json, yamlpython 生成代码部分可无视。

一、openapi 整体结构

官方文档

1
openapi: 3.0.0 # 指定openapi版本
2
info: # 说明当前文档信息
3
title: 测试 # 标题
4
description: 测试api # 具体说明支持 markdown
5
version: 0.0.1 # 版本
6
paths: {} # 各个url下的api说明对象
7
tags: [] # 分组用的tag
8
components: # 多次复用的一些对象
9
schemas: {} # 复用的数据结构
10
parameters: {} # 复用的请求参数
11
responses: {} # 复用的响应参数
12
securitySchemes: {} # 认证信息

把以上代码贴到 Swagger Editor 可以看到如下效果:

初始化

构造 ApiSpec 对象, 简单的生成配置函数

1
import yaml
2
3
4
class ApiSpec:
5
def __init__(self, title, description, version):
6
self._paths = {}
7
self._tags = []
8
self._schemas = {}
9
self._parameters = {}
10
self._responses = {}
11
self._security_schemes = {}
12
self._spec = {
13
"openapi": "3.0.0",
14
"info": {
15
"title": title,
16
"description": description,
17
"version": version
18
},
19
"paths": self._paths,
20
"tags": self._tags,
21
"components": {
22
"schemas": self._schemas,
23
"parameters": self._parameters,
24
"responses": self._responses,
25
"securitySchemes": self._security_schemes
26
}
27
}
28
def to_dict(self):
29
return self._spec
30
31
def to_yaml(self):
32
return yaml.dump(self.to_dict())
33
if __name__ == "__main__":
34
print(ApiSpec("测试", "测试api", "0.0.1").to_yaml())

最终会生成如下 yaml 代码实际上是和上面的示例等价。

1
components:
2
parameters: {}
3
responses: {}
4
schemas: {}
5
securitySchemes: {}
6
info: { description: "\u6D4B\u8BD5api", title: "\u6D4B\u8BD5", version: 0.0.1 }
7
openapi: 3.0.0
8
paths: {}
9
tags: []

二、添加一个 api

这里只写代码片段

响应体

path 文档
响应文档

1
paths:
2
/user: # url
3
get: # 请求方法
4
responses: # 响应
5
200: # 响应状态
6
description: ok # 响应说明
7
content: # 响应内容
8
application/json: # 响应格式
9
schema: # 格式描述
10
type: object # 类型(integer|number|boolean|string| array|object)
11
properties: # object 专用用于描述各个字段
12
name: # 字段名
13
type: string # 字段类型可继续使用 object 向下继续描述
14
description: 名字 # 字段说明
15
email:
16
type: string
17
description: 邮箱
18
tags:
19
type: array
20
description: 标签
21
items: # array专用 描述item
22
type: string
  • 上面的 application/json 可用换成支持的格式如 text/yaml
  • 暂不支持 map[string]any 之类的类型
  • 显示效果:
    get-api.png

url 参数

官方文档

1
paths:
2
/user/{user_id}:
3
get:
4
parameters:
5
- in: path
6
name: user_id
7
schema:
8
type: integer
9
required: true
10
description: 用户id
11
- in: query
12
name: order
13
schema:
14
type: integer
15
description: 排序

还有一些在 Cookie, Header 中的配置,这里就不一一说明了,请自行阅读 官方文档

内容体参数

官方文档

1
paths:
2
/user:
3
post:
4
requestBody: # 内容体描述
5
description: 内容体说明可用*markdown* # 说明可用markdown
6
required: true # 是否必须传递内容体
7
content: # 这里往下与 `responses` 的完全相同
8
application/json:
9
schema:
10
type: object
11
properties:
12
name:
13
type: string
14
responses:
15
200:
16
description: ok

效果:
requestBody.png

对象引用

$ref 文档
schema 使用$ref