如何使用Flask通过静态.yaml文件生成OpenAPI文档(Swagger UI)页面

1. 安装依赖 #

首先安装需要的第三方包：
pip install flask flask-swagger-ui

2. 整理项目结构 #

你可以按照自己的习惯存放静态YAML文件，参考结构如下：

你的项目根目录/
├── app.py                 # Flask启动入口文件
└── swagger/               # 自定义的YAML文件存放目录
    └── api_spec.yaml      # 你提前写好的OpenAPI/Swagger规范YAML文件

3. 编写服务代码 #

from flask import Flask, send_from_directory
from flask_swagger_ui import get_swaggerui_blueprint

app = Flask(__name__)

# 自定义配置
SWAGGER_DOCS_ROUTE = "/api/docs"  # API文档的访问路径
SWAGGER_YAML_ROUTE = "/api/spec.yaml"  # 暴露本地YAML文件的路由

# 实现路由返回本地YAML文件内容
@app.route(SWAGGER_YAML_ROUTE)
def serve_swagger_spec():
    # 第一个参数为本地YAML文件存放的目录路径，第二个参数为YAML文件名
    return send_from_directory("./swagger", "api_spec.yaml")

# 注册Swagger UI蓝图
swagger_bp = get_swaggerui_blueprint(
    SWAGGER_DOCS_ROUTE,
    SWAGGER_YAML_ROUTE,
    config={
        "app_name": "你的API服务名称"
    }
)
app.register_blueprint(swagger_bp, url_prefix=SWAGGER_DOCS_ROUTE)

if __name__ == "__main__":
    app.run(debug=True)

4. 使用说明 #

• 启动服务后，访问 http://localhost:5000/api/docs 即可查看渲染完成的API文档
• 直接修改本地api_spec.yaml的内容，刷新文档页面即可生效，无需修改服务代码
• 如果你的YAML文件存放在其他路径，只需修改send_from_directory的第一个参数为对应本地目录即可

注意：生产环境部署请关闭debug模式，按需限制YAML文件的访问权限，避免泄露敏感信息。

内容的提问来源于stack exchange，提问作者Eduard