swagger python

### Python 中使用 Swagger 进行 API 文档创建与管理

#### 工具选择
对于 Python 项目而言，有多个库可以实现与 Swagger 的集成来帮助管理和生成 API 文档。其中较为流行的几个选项包括 `connexion`、`Flasgger` 和已经不再推荐使用的 `Flask-RESTPlus`[^1]。

#### Connexion 库简介
Connexion 是一个基于 OpenAPI 规范（以前称为 Swagger 规范）构建的扩展，不仅能够为 Flask 或者 Abstract Application 提供 REST API 接口定义文件的支持，还允许应用程序严格遵循这些规格声明的行为工作。这意味着如果请求不符合路径参数、查询字符串或正文中指定的数据结构，则会自动拒绝它们。这有助于减少错误并提高安全性。

#### Flasgger 库特性
Flasgger 则专注于简化过程，它与 Flask Web 框架紧密合作，在应用内部嵌入了交互式的 API 测试环境——即所谓的 Swagger UI 页面。这样做的好处在于开发人员可以在本地环境中轻松地探索自己的 API 功能而不需要额外配置任何东西。

#### 实现步骤概述
要在一个现有的 Python/Flask 项目里加入 Swagger 支持，可以选择安装上述提到的一个合适的库，并按照官方指南完成必要的设置：

对于 **Flasgger** 来说，

from flasgger import Swagger, swag_from
app = Flask(__name__)
swagger_config = {
    "headers": [],
    "specs": [
        {
            "endpoint": 'apispec_1',
            "route": '/apispec_1.json'
        }
    ],
    "static_url_path": "/flasgger_static",
}
Swagger(app, config=swagger_config)

@app.route('/example')
@swag_from('path_to_your_swagger_file.yaml') # 加载外部YAML描述文件
def example():
    return {"message": "Hello world"}

而对于 **Connexion** ，则更倾向于直接从 YAML 文件加载整个 API 结构：

import connexion
app = connexion.App(__name__, specification_dir='.')
app.add_api('openapi.yml')

if __name__ == '__main__':
    app.run(port=8080)