能否用flask-RESTplus自动生成Swagger元数据JSON并暴露JSON格式API文档？

嘿，好问题！我正好用flask-RESTplus处理过类似的需求，这两个点都有现成的解决方案，咱们一步步说清楚：

完全可以！flask-RESTplus本身就是基于OpenAPI（原Swagger）规范构建的，它会在你定义API接口、命名空间、数据模型的过程中，自动生成符合规范的Swagger元数据JSON。你不需要手动编写任何Swagger相关的JSON代码，只要按照flask-RESTplus的规则使用装饰器、定义模型，后台就会自动把这些信息转换成标准的Swagger元数据。

这个需求也很容易实现，flask-RESTplus默认就支持暴露Swagger元数据的JSON端点，甚至可以自定义路径来匹配你想要的http://serverURL:80/api/v1/documentation.json格式。

具体实现方式： #

在初始化Api对象的时候，通过specs_url参数指定JSON文档的访问路径，同时用doc参数指定Swagger UI的地址，示例代码如下：

from flask import Flask
from flask_restplus import Api, Resource, fields

app = Flask(__name__)

# 初始化API，同时配置Swagger UI和JSON文档的路径
api = Api(
    app,
    version='1.0',
    title='我的示例API',
    description='演示flask-RESTplus生成JSON格式API文档',
    doc='/api/v1/documentation/',  # Swagger UI的访问地址
    specs_url='/api/v1/documentation.json'  # JSON格式文档的访问地址
)

# 下面是常规的API定义示例
ns = api.namespace('users', description='用户相关操作')

# 定义数据模型
user_model = api.model('User', {
    'id': fields.Integer(readOnly=True, description='用户唯一ID'),
    'name': fields.String(required=True, description='用户名'),
    'email': fields.String(required=True, description='用户邮箱')
})

# 模拟数据源
USERS = [
    {'id': 1, 'name': '张三', 'email': 'zhangsan@example.com'},
    {'id': 2, 'name': '李四', 'email': 'lisi@example.com'}
]

@ns.route('/')
class UserList(Resource):
    @ns.doc('list_users')
    @ns.marshal_list_with(user_model)
    def get(self):
        '''获取所有用户列表'''
        return USERS

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=80, debug=True)

效果验证： #

启动服务后：

• 访问 http://serverURL:80/api/v1/documentation 就能看到熟悉的Swagger UI界面；
• 访问 http://serverURL:80/api/v1/documentation.json 就能直接获取JSON格式的API元数据，和Swashbuckle的效果完全一致。

额外小技巧： #

如果你需要在代码内部直接获取Swagger元数据，不需要通过HTTP请求，也可以直接访问api.__schema__属性，它是一个Python字典，包含了完整的Swagger规范内容，你可以直接序列化或者做其他自定义处理。

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