Swagger最大的好处是与代码在一起生成文档,理论上你改完了代码,文档也接着更新了。良好的解决了常规情况下文档与代码不一致的情况。
本文主要记录python的常用框架与swagger集成的问题。
编写文档
swagger: "2.0" info: version: 1.0.0 title: HelloWorld API description: A simple API to learn how to write OpenAPI Specification schemes: - https host: api.domain.io basePath: /helloworld paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. responses: 200: description: A list of Person schema: type: array items: required: - username properties: firstName: type: string
使用swagger-codegen
官方地址在: https://github.com/swagger-api/swagger-codegen
使用pip3安装
pip3 install swagger-py-codegen
生成代码
- 其中helloworld.yml文件参考前面的文档,也可以自行编写。
- swagger本身的规范移步谷歌即可。
swagger_py_codegen –swagger-doc helloworld.yml helloworld-py-app
generate helloworld-py-app/helloworld_py_app/helloworld/schemas.py generate helloworld-py-app/helloworld_py_app/helloworld/routes.py generate helloworld-py-app/helloworld_py_app/helloworld/api/persons.py generate helloworld-py-app/helloworld_py_app/helloworld/validators.py generate helloworld-py-app/helloworld_py_app/helloworld/api/__init__.py generate helloworld-py-app/helloworld_py_app/helloworld/__init__.py generate helloworld-py-app/helloworld_py_app/__init__.py generate helloworld-py-app/requirements.txt
可选参数
如果不指定-tlp参数,默认将使用flask作为框架,如果指定–ui –spec则会在-p指定的目录下生成ui目录static
swagger_py_codegen –help
Usage: swagger_py_codegen [OPTIONS] DESTINATION Options: -s, --swagger-doc TEXT Swagger doc file. [required] -f, --force Force overwrite. -p, --package TEXT Package name / application name. -t, --template-dir TEXT Path of your custom templates directory. --spec, --specification Generate online specification json response. --ui Generate swagger ui. --validate Validate swagger file. -tlp, --templates TEXT gen flask/tornado/falcon/sanic templates, default flask. --version Show current version. --help Show this message and exit.
swagger_py_codegen –swagger-doc helloworld.yml helloworld-py-app-ui –ui –spec
generate helloworld-py-app-ui/helloworld_py_app_ui/static/swagger-ui generate helloworld-py-app-ui/helloworld_py_app_ui/helloworld/schemas.py generate helloworld-py-app-ui/helloworld_py_app_ui/helloworld/routes.py generate helloworld-py-app-ui/helloworld_py_app_ui/helloworld/api/persons.py generate helloworld-py-app-ui/helloworld_py_app_ui/static/helloworld/swagger.json generate helloworld-py-app-ui/helloworld_py_app_ui/helloworld/validators.py generate helloworld-py-app-ui/helloworld_py_app_ui/helloworld/api/__init__.py generate helloworld-py-app-ui/helloworld_py_app_ui/helloworld/__init__.py generate helloworld-py-app-ui/helloworld_py_app_ui/__init__.py generate helloworld-py-app-ui/requirements.txt generate helloworld-py-app-ui/helloworld_py_app_ui/static/swagger-ui/index.html
此时可以看到app框架已经生成了,routes.py是自动生成的路由,运行init.py
python3 init.py
* Serving Flask app "__init__" (lazy loading) * Environment: production WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead. * Debug mode: on * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) * Restarting with stat * Debugger is active! * Debugger PIN: 851-087-703
访问http://127.0.0.1:5000/static/swagger-ui/index.html
- 最终效果如下:

使用sanic模板
生成框架代码
swagger_py_codegen –swagger-doc helloworld.yml helloworld-app-sanic-ui –ui –spec -tlp sanic
generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/static/swagger-ui generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/helloworld/schemas.py generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/helloworld/routes.py generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/helloworld/api/persons.py generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/static/helloworld/swagger.json generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/helloworld/validators.py generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/helloworld/api/__init__.py generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/helloworld/__init__.py generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/__init__.py generate helloworld-app-sanic-ui/requirements.txt generate helloworld-app-sanic-ui/helloworld_app_sanic_ui/static/swagger-ui/index.html
下载依赖
cd helloworld-app-sanic-ui/
pip3 install -r requirements.txt
版权声明
本文标题:107-python3集成flask及swagger
文章作者:盛领
发布时间:2020年09月26日 - 04:47:11
原始链接:http://blog.xiaoyuyu.net/post/8e7e2220.html
许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。
如您有任何商业合作或者授权方面的协商,请给我留言:sunsetxiao@126.com
