Flask 配置并使用 Swagger 服務(wù).
flask-swagger 是什么
在使用之前栅组,我們先來了解下 flask-swagger
是什么瑟俭,如下內(nèi)容障斋,來自官網(wǎng)。
flask-swagger
提供 swagger
方法泪掀,可以掃描 flask 中包含 yaml 格式的文檔注釋听绳,文檔注釋格式與 Swagger 2.0 Operation 對象一致。
例如:
class UserAPI(MethodView):
def post(self):
"""
Create a new user
---
tags:
- users
definitions:
- schema:
id: Group
properties:
name:
type: string
description: the group's name
parameters:
- in: body
name: body
schema:
id: User
required:
- email
- name
properties:
email:
type: string
description: email for user
name:
type: string
description: name for user
address:
description: address for user
schema:
id: Address
properties:
street:
type: string
state:
type: string
country:
type: string
postalcode:
type: string
groups:
type: array
description: list of groups
items:
$ref: "#/definitions/Group"
responses:
201:
description: User created
"""
return {}
flask-swagger
支持 MethodView
方法級別的文檔注釋和普通 flask view
方法异赫。
底層實現(xiàn):應(yīng)用掃描文檔椅挣,把文檔注釋中---
前,第一張內(nèi)容作為 summary
字段塔拳,其余行作為description
字段鼠证,---
之后的文檔注釋,作為 Swagger Operation
對象處理靠抑。
支持在注釋中添加 Parameter 和 Response 支持內(nèi)聯(lián)的 Schema對象量九,
另外,docstring 也可以放到額外的文件中颂碧。
eg.
Create a new user
---
tags:
- users
definitions:
- schema:
id: Group
properties:
name:
type: string
description: the group's name
parameters:
- in: body
name: body
schema:
id: User
required:
- email
- name
properties:
email:
type: string
description: email for user
name:
type: string
description: name for user
address:
description: address for user
schema:
id: Address
properties:
street:
type: string
state:
type: string
country:
type: string
postalcode:
type: string
groups:
type: array
description: list of groups
items:
$ref: "#/definitions/Group"
responses:
201:
description: User created
使用時荠列,在文檔注釋中添加:
class UserAPI(MethodView):
def post(self):
"""
Create a new user
blah blah
swagger_from_file: path/to/file.yml
blah blah
"""
return {}
swagger_from_file
可以替換.
安裝使用
了解基礎(chǔ)之后,開始安裝并配置使用稚伍,先安裝這個庫弯予。
pip install flask-swagger
另外戚宦,需要在 flask 中配置 spec
@app.route("/spec")
def spec():
swag = swagger(app)
swag['info']['version'] = "1.0"
swag['info']['title'] = "My API"
return jsonify(swag)
現(xiàn)在配置可以生成 json 格式的 OpenAPI 內(nèi)容了个曙。只有 json 有什么用,我們需要Web頁面的Swagger可以訪問。另外還需要將 json 放到 swagger-ui 中. swagger-ui 的地址如下: https://github.com/swagger-api/swagger-ui垦搬。
swagger-ui
項目包含靜態(tài)的頁面呼寸,為了方便,我們將靜態(tài)頁面猴贰,放到 flask 項目的靜態(tài)頁面中对雪,如下圖所示。
修改 swagger index.html
中默認(rèn)的URL https://petstore.swagger.io/v2/swagger.json
改成通過 flask 傳入的地址 {{ url }}
米绕,這樣做的目的是瑟捣,我們可以在配置或者業(yè)務(wù)中,動態(tài)修改URL, 如下栅干。
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
// url: "https://petstore.swagger.io/v2/swagger.json",
url: "{{ url }}",
"dom_id": "#swagger-ui",
...
})
URL通常包括請求協(xié)議迈套,請求地址和端口,這里碱鳞,我們將這些參數(shù)寫到配置文件中桑李,這樣傳遞:
@app.route('/swagger')
def swagger_index():
return render_template("swagger/index.html", **{
"url": "http://" + config.IP_ADDRESS + ":" + str(config.PORT) + "/spec"
})
最終的效果如下所示
)
完整的代碼示例,可通過 https://github.com/RiverLiu/demos/tree/master/python/flask-swagger-example 下載.
附錄
OpenAPI Specification 2.0
- OpenAPI 說明 2.0 中文版: https://blog.csdn.net/wjc133/article/details/65436778
- 英文原版:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
OpenApi 3.0.3
Notes
swagger-ui 存在版本兼容的問題窿给,swagger 有 2.0 和 3.0 版本贵白,flask-swagger 3.18.3
版支持 swagger 2.0 和 3.0