Swagger是一个基于网络的API文档框架。它被用来为API创建交互式文档,这些API是为特定目的而建立的。与其他文档类型相比,Swagger UI文档享有许多优势。
- 它是开源的
- 使你能够创建和分享API文档
- 允许你测试API
在这篇文章中,我将逐步解释创建Swagger UI文档的过程,以便通过Flask REST API框架中构建的API获得 "Hello World "响应。我将使用Python和YAML文件来实现Swagger UI和API,并给出解释。
作为前提条件,你应该对Flask APIs及其工作原理有一个基本的了解。如果你需要对Flask APIs有一个基本的了解,你可以参考官方的Flask RESTful API文档。
创建Swagger UI文档的步骤
我们将按照以下步骤为一个API函数建立一个Swagger UI文档。
- 首先,我们将使用Flask web API框架创建API。
- 接下来,我们将创建一个JSON或YAML文件,在SwaggerUI中实现API功能。
- 最后,我们将在有API定义的Python程序中调用创建的JSON或YAML文件。
你需要使用pip install
安装以下Python包来运行这个例子。
$ pip install Flask
$ pip install flasgger
如果你想在安装时更新模块,你可以使用pip install -U <module_name>
,或者如果你使用Python虚拟环境,希望为你的项目安装特定版本的模块,你可以执行pip install <module_name>==<version>
,例如,pip install Flask==2.0.0
。
但我建议你应该安装最新的版本。下面是我们Python脚本的导入块。
from flask import Flask, request
from flasgger import Swagger, LazyString, LazyJSONEncoder
from flasgger import swag_from
使用Flask方法定义Flask应用。
app = Flask(__name__)
你需要JSON编码器来从API对象创建JSON,为此你可以使用LazyJSONEncoder类。
app.json_encoder = LazyJSONEncoder
Swagger UI文档的模板和配置被定义为如下的字典对象。
swagger_template = dict(
info = {
'title': LazyString(lambda: 'My first Swagger UI document'),
'version': LazyString(lambda: '0.1'),
'description': LazyString(lambda: 'This document depicts a sample Swagger UI document and implements Hello World functionality after executing GET.'),
},
host = LazyString(lambda: request.host)
)
swagger_config = {
"headers": [],
"specs": [
{
"endpoint": 'hello_world',
"route": '/hello_world.json',
"rule_filter": lambda rule: True,
"model_filter": lambda tag: True,
}
],
"static_url_path": "/flasgger_static",
"swagger_ui": True,
"specs_route": "/apidocs/"
}
flasgger
模块的LazyString
功能是用来在运行时为某些参数设置默认值。Swagger UI文档的参数,如文档标题、版本、描述等,在info
字段中定义。API的基本URL在 "host "字段中指定。Swagger UI的配置细节在swagger_config
JSON对象中定义。
最后,使用从flasgger
模块导入的Swagger方法来定义swagger对象,如下所示。
swagger = Swagger(app, template=swagger_template,
config=swagger_config)
API函数被定义,Flask应用程序的路由/地址使用@app.route
装饰器指定。通过指定YAML文件的路径和GET
方法作为参数(参数如POST
、PUT
、DELETE
也可按要求使用),使用@swag_from
装饰器调用Swagger UI文档的YAML文件。
@swag_from("hello_world.yml", methods=['GET'])
@app.route("/")
def hello_world():
return "Hello World!!!"
注意: 在这种情况下,YAML文件和Python文件应该在同一个目录下。如果不是,YAML文件的正确路径应该在
*@swag_from*
*decorator参数中指定。
为了在Swagger UI中实现GET
响应,应该在hello_world.yml
文件中添加以下几行:
openapi: 3.0.0
tags:
- name: Hello World
get:
description: None
responses:
'200':
description: Successful response
'400':
description: Bad Request
'500':
description: Internal Server Error
***注意:***如果GET响应没有任何参数需要填写,那么将描述指定为None并在最后定义响应是一个好的做法。
最后,Flask应用程序被运行并在main内部使用以下几行代码执行:
if __name__ == '__main__':
app.run()
代码执行时将在开发模式下运行在localhost
上,运行127.0.0.1:5000/apidocs
时显示以下文件。
正如你所看到的,这个文档包含了YAML文件中定义的API的标题、版本和描述。一旦在Swagger UI文档中选择了GET响应,该文档就会展开为:
当你点击**"试用"按钮时,文件会显示"执行 "**按钮,如下所示。
一旦选择了**"执行 "**选项,"helloworld "的输出就会显示出来,如下所示。
正如所见,API响应被返回到GET方法的 "响应体 "中。响应头 "包含响应的基本信息,如响应的长度、响应的类型、收到响应的日期和时间(时间将按GMT时区显示)等。