创建Swagger UI文档的步骤

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时区显示）等。