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