使用 Flask-Docs 自动生成 Api 文档

影响我写文档的原因可能是代码和文档分离，有时候写完代码会忘记补文档，而且不能及时查看，使用 Flask-Docs 可以解决我的问题，这个插件可以根据代码注释生成文档页面，代码注释改动文档可以及时更新，而且支持离线文档下载。

Flask-Docs

Flask Api 文档自动生成插件

特性

• 根据代码注释自动生成文档
• 支持离线 markdown 文档下载
• 支持 Flask-RESTful
• 支持 flask.views.MethodView

安装

pip3 install Flask-Docs

使用

from flask import Flask
from flask_docs import ApiDoc

app = Flask(__name__)

# 使用 CDN
# app.config["API_DOC_CDN"] = True

# 禁用文档页面
# app.config["API_DOC_ENABLE"] = False

# 允许显示的方法
# app.config["API_DOC_METHODS_LIST"] = ["GET", "POST", "PUT", "DELETE", "PATCH"]

# 自定义 url_prefix
# app.config["API_DOC_URL_PREFIX"] = "/docs/api"

# 需要排除的 RESTful Api 文档
# app.config["API_DOC_RESTFUL_EXCLUDE"] = ["todo"]

# 需要显示文档的 Api
app.config["API_DOC_MEMBER"] = ["api", "platform"]

ApiDoc(app)

如何书写 markdown 格式文档

@@@
在注释结尾用 "@@@" 包含 markdown 格式文档
@@@

查看文档页面

http://127.0.0.1/docs/api/

Api demo

@api.route("/add_data", methods=["POST"])
def add_data():
    """Add some data

    @@@
    ### args
    |  args | nullable | request type | type |  remarks |
    |-------|----------|--------------|------|----------|
    | title |  false   |    body      | str  | blog title    |
    | name  |  false   |    body      | str  | person's name |

    ### request
    ```json
    {"title": "xxx", "name": "xxx"}
    ```

    ### return
    ```json
    {"code": xxxx, "msg": "xxx", "data": null}
    ```
    @@@
    """
    return jsonify({"api": "add data"})

sample_app_add.png

@api.route("/delete_data", methods=["GET"])
def delete_data():
    """Delete some data

    @@@
    ### args
    |  args  | nullable | request type | type |  remarks     |
    |--------|----------|--------------|------|--------------|
    |  id    |  true    |    query     |  str | blog id    |
    |  name  |  false   |    query     |  str | person's name |

    ### request
    ```
    http://127.0.0.1:5000/api/delete_data?name=xxx
    ```
    
    ### return
    ```json
    {"code": xxxx, "msg": "xxx", "data": null}
    ```
    @@@
    """
    
    return jsonify({"api": "delete data"})

sample_app_delete.png

@platform.route("/get_something", methods=["GET"])
def get_something():
    """Get some data

    @@@
    ### request example
    ```python
    import requests
    url="http://127.0.0.1:5000/platform/get_something"
    try:
        print(requests.get(url).text)
    except:
        pass
    ```

    ### return
    ```json
    {"code": xxxx, "msg": "xxx", "data": null}
    ```
    @@@
    """
    
    return jsonify({"platform": "get something"})

sample_app_get.png

完整代码

#!/usr/bin/env python
# -*- coding:utf-8 -*-

from flask import Blueprint, Flask, jsonify

from flask_docs import ApiDoc

app = Flask(__name__)

# Using CDN
# app.config["API_DOC_CDN"] = True

# Disable document pages
# app.config["API_DOC_ENABLE"] = False

# Methods allowed to be displayed
# app.config["API_DOC_METHODS_LIST"] = ["GET", "POST", "PUT", "DELETE", "PATCH"]

# Custom url_prefix
# app.config["API_DOC_URL_PREFIX"] = "/docs/api"

# Api Document needs to be displayed
app.config["API_DOC_MEMBER"] = ["api", "platform"]

ApiDoc(app, title="Sample App", version="1.0.0")

api = Blueprint("api", __name__)
platform = Blueprint("platform", __name__)


@api.route("/add_data", methods=["POST"])
def add_data():
    """Add some data
    @@@
    ### args
    |  args | nullable | request type | type |  remarks |
    |-------|----------|--------------|------|----------|
    | title |  false   |    body      | str  | blog title    |
    | name  |  false   |    body      | str  | person's name |
    ### request
    ```json
    {"title": "xxx", "name": "xxx"}
    ```
    ### return
    ```json
    {"code": xxxx, "msg": "xxx", "data": null}
    ```
    @@@
    """
    return jsonify({"api": "add data"})


@api.route("/delete_data", methods=["GET"])
def delete_data():
    """Delete some data
    @@@
    ### args
    |  args  | nullable | request type | type |  remarks     |
    |--------|----------|--------------|------|--------------|
    |  id    |  true    |    query     |  str | blog id    |
    |  name  |  false   |    query     |  str | person's name |
    ### request
    ```
    http://127.0.0.1:5000/api/delete_data?name=xxx
    ```
    ### return
    ```json
    {"code": xxxx, "msg": "xxx", "data": null}
    ```
    @@@
    """

    return jsonify({"api": "delete data"})


@platform.route("/get_something", methods=["GET"])
def get_something():
    """Get some data
    @@@
    ### request example
    ```python
    import requests
    url="http://127.0.0.1:5000/platform/get_something"
    try:
        print(requests.get(url).text)
    except:
        pass
    ```
    ### return
    ```json
    {"code": xxxx, "msg": "xxx", "data": null}
    ```
    @@@
    """

    return jsonify({"platform": "get something"})


app.register_blueprint(api, url_prefix="/api")
app.register_blueprint(platform, url_prefix="/platform")

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

Flask-RESTful Api demo

from flask_restful import Resource, Api

class Todo(Resource):
    """Manage todo"""

    def post(self):
        """Add todo

        @@@
        ### description
        > Add todo

        ### args
        |  args | nullable | request type | type |  remarks |
        |-------|----------|--------------|------|----------|
        |  name |  false   |    body      | str  | todo name |
        |  type |  false   |    body      | str  | todo type |

        ### request
        ```json
        {"name": "xx", "type": "code"}
        ```

        ### return
        ```json
        {"code": xxxx, "msg": "xxx", "data": null}
        ```
        @@@
        """
    
        return {"todo": "post todo"}
    
    def get(self):
        """Get todo
    
        @@@
        ### description
        > Get todo
    
        ### args
        |  args | nullable | request type | type |  remarks |
        |-------|----------|--------------|------|----------|
        |  name |  false   |    query     | str  | todo name |
        |  type |  true    |    query     | str  | todo type |
    
        ### request
        ```
        http://127.0.0.1:5000/todo?name=xxx&type=code
        ```
    
        ### return
        ```json
        {"code": xxxx, "msg": "xxx", "data": null}
        ```
        @@@
        """
    
        return {"todo": "get todo"}


restful_api.add_resource(Todo, "/todo")

sample_app_restful_post.png

sample_app_restful_get.png

完整代码

#!/usr/bin/env python
# -*- coding:utf-8 -*-

from flask import Flask
from flask_restful import Api, Resource

from flask_docs import ApiDoc

app = Flask(__name__)

# Using CDN
# app.config["API_DOC_CDN"] = True

# Disable document pages
# app.config["API_DOC_ENABLE"] = False

# Methods allowed to be displayed
# app.config["API_DOC_METHODS_LIST"] = ["GET", "POST", "PUT", "DELETE", "PATCH"]

# Custom url_prefix
# app.config["API_DOC_URL_PREFIX"] = "/docs/api"

# RESTful Api documents to be excluded
# app.config["API_DOC_RESTFUL_EXCLUDE"] = ["todo"]

restful_api = Api(app)
ApiDoc(app, title="Sample App Restful", version="1.0.0")


class Todo(Resource):
    """Manage todo"""

    def post(self):
        """Add todo
        @@@
        ### description
        > Add todo
        ### args
        |  args | nullable | request type | type |  remarks |
        |-------|----------|--------------|------|----------|
        |  name |  false   |    body      | str  | todo name |
        |  type |  false   |    body      | str  | todo type |
        ### request
        ```json
        {"name": "xx", "type": "code"}
        ```
        ### return
        ```json
        {"code": xxxx, "msg": "xxx", "data": null}
        ```
        @@@
        """

        return {"todo": "post todo"}

    def get(self):
        """Get todo
        @@@
        ### description
        > Get todo
        ### args
        |  args | nullable | request type | type |  remarks |
        |-------|----------|--------------|------|----------|
        |  name |  false   |    query     | str  | todo name |
        |  type |  true    |    query     | str  | todo type |
        ### request
        ```
        http://127.0.0.1:5000/todo?name=xxx&type=code
        ```
        ### return
        ```json
        {"code": xxxx, "msg": "xxx", "data": null}
        ```
        @@@
        """

        return {"todo": "get todo"}


restful_api.add_resource(Todo, "/todo")

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

flask.views.MethodView Api demo

目前只支持与类名相同的 url_rule

from flask.views import MethodView

class TodoList(MethodView):
    """Manage todolist"""

    def put(self):
        """Change the data
        """
        return jsonify({"todos": "put todolist"})

    def delete(self):
        """Delete the data
        """
        return jsonify({"todos": "delete todolist"})


app.add_url_rule("/todolist/", view_func=TodoList.as_view("todolist"))

装饰器 @ApiDoc.change_doc

复用注释

from flask_docs import ApiDoc

return_json_str = '{"code": xxxx, "msg": "xxx", "data": null}'

@api.route("/add_data", methods=["POST"])
@ApiDoc.change_doc({"return_json": return_json_str})
def add_data():
    """Add some data

    @@@
    ### return
    ```json
    return_json
    ```
    @@@
    """
    return jsonify({"api": "add data"})


@api.route("/delete_data", methods=["GET"])
@ApiDoc.change_doc({"return_json": return_json_str})
def delete_data():
    """Delete some data

    return_json
    """
    
    return jsonify({"api": "delete data"})