小皮博客 | Xiaopi's Blog

107-python3集成flask及swagger

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

盛领 wechat
欢迎您扫一扫上面的微信公众号,订阅我的博客!
坚持原创技术分享,您的支持将鼓励我继续创作!