使用 Flask-Docs 自動生成 Api 文檔

影響我寫文檔的原因可能是代碼和文檔分離，有時候寫完代碼會忘記補文檔，而且不能及時查看，使用 Flask-Docs 可以解決我的問題，這個插件可以根據代碼註釋生成文檔頁面，代碼註釋改動文檔可以及時更新，而且支持離線文檔下載。

Flask-Docs

Flask Api 文檔自動生成插件

特性

• 根據代碼註釋自動生成文檔
• 支持 Flask-RESTful
• 支持離線 markdown 文檔下載

安裝

pip install Flask-Docs

使用

from flask import Flask
from flask_docs import ApiDoc

app = Flask(__name__)

# 本地加載
# app.config['API_DOC_CDN'] = False

# 禁用文檔頁面
# app.config['API_DOC_ENABLE'] = False

# 需要顯示文檔的 Api
app.config['API_DOC_MEMBER'] = ['api', 'platform']

# 需要排除的 RESTful Api 文檔
app.config['RESTFUL_API_DOC_EXCLUDE'] = []

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

    Add some data in this routing

    Args:
        pass

    Returns:
        pass
    """
    return jsonify({'api': 'add data'})

@api.route('/del_data', methods=['POST'])
def del_data():
    """Del some data

    @@@
    #### args

    | args | nullable | type | remark |
    |--------|--------|--------|--------|
    |    title    |    false    |    string   |    blog title    |
    |    name    |    true    |    string   |    person's name    |

    #### return
    - ##### json
    > {"msg": "success", "code": 200}
    @@@
    """
    return jsonify({'api': 'del data'})

@platform.route('/get_something', methods=['GET'])
def get_something():
    """
    @@@
    #### example
        import requests
        url='http://127.0.0.1:5000/api/get_something'
        try:
            print requests.get(url).text
        except:
            pass
    @@@
    """
    return jsonify({'platform': 'get something'})

完整代碼

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

from flask import Flask, render_template, jsonify, Blueprint
from flask_docs import ApiDoc

app = Flask(__name__)

# Local loading
# app.config['API_DOC_CDN'] = False

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

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

ApiDoc(app)

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


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

    Add some data in this routing

    Args:
        pass
 
    Returns:
        pass
    """
    return jsonify({'api': 'add data'})


@api.route('/del_data', methods=['POST'])
def del_data():
    """Del some data

    @@@
    #### args

    | args | nullable | type | remark |
    |--------|--------|--------|--------|
    |    title    |    false    |    string   |    blog title    |
    |    name    |    true    |    string   |    person's name    |

    #### return
    - ##### json
    > {"msg": "success", "code": 200}
    @@@
    """
    return jsonify({'api': 'del data'})


@platform.route('/get_something', methods=['GET'])
def get_something():
    """
    @@@
    #### example
        import requests
        url='http://127.0.0.1:5000/api/get_something'
        try:
            print requests.get(url).text
        except:
            pass
    @@@
    """
    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 TodoList(Resource):
    """Manage todolist"""

    def post(self):
        """Submission of data

        Args:
            pass

        Returns:
            pass

        """
        return {'todos': 'post todolist'}

    def get(self):
        """
        @@@
        #### args

        | args | nullable | type | remark |
        |--------|--------|--------|--------|
        |    id    |    false    |    int   |    todo id    |

        #### return
        - ##### json
        > {...}
        @@@
        """
        return {'todos': 'get todolist'}


restful_api.add_resource(TodoList, '/todolist')

完整代碼

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

from flask import Flask
from flask_restful import Resource, Api
from flask_docs import ApiDoc

app = Flask(__name__)

# Local loading
# app.config['API_DOC_CDN'] = False

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

# RESTful Api documents to be excluded
app.config['RESTFUL_API_DOC_EXCLUDE'] = []

restful_api = Api(app)
ApiDoc(app)


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

    def post(self):
        """Submission of data

        Args:
            pass
    
        Returns:
            pass

        """
        return {'todos': 'post todolist'}

    def get(self):
        """
        @@@
        #### args

        | args | nullable | type | remark |
        |--------|--------|--------|--------|
        |    id    |    false    |    int   |    todo id    |

        #### return
        - ##### json
        > {...}
        @@@
        """
        return {'todos': 'get todolist'}


restful_api.add_resource(TodoList, '/todolist')

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