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

邹强发布于2019-07-30 17:06 / 499人阅读

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

影响我写文档的原因可能是代码和文档分离，有时候写完代码会忘记补文档，而且不能及时查看，使用 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)

云服务器混合云生成API文档 api文档文档生成 api帮助文档

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/42012.html

如何利用showdoc自动生成API文档

摘要：仿照此种写法，在你的项目中插入类似的注释，也能达到自动生成文档的效果。执行以下命令，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成文档。如果是，程序会自动进行格式化展示。介绍 showdoc是一个适合IT团队的文档工具，阅读本文前需要对showdoc有基本了解。基本介绍可看：https://www.showdoc.cc/help 对于写API文档这件事，虽然说文本编辑...

linkin 2019-07-01 10:32 评论0 收藏0
如何利用showdoc自动生成API文档

摘要：仿照此种写法，在你的项目中插入类似的注释，也能达到自动生成文档的效果。执行以下命令，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成文档。如果是，程序会自动进行格式化展示。介绍 showdoc是一个适合IT团队的文档工具，阅读本文前需要对showdoc有基本了解。基本介绍可看：https://www.showdoc.cc/help 对于写API文档这件事，虽然说文本编辑...

周国辉 2019-08-26 12:16 评论0 收藏0
【效率专精系列】善用API统一描述语言提升RestAPI开发效率

摘要：其标准为前身是，提供强大的在线编辑功能，包括语法高亮错误提示自动完成实时预览，并且支持用户以格式撰写导入导出转换文档。团队内部RestAPI开发采用设计驱动开发的模式，即使用API设计文档解耦前端和后端的开发过程，双方只在联调与测试时耦合。在实际开发和与前端合作的过程中，受限于众多因素的影响，开发效率还有进一步提高的空间。本文的目的是优化工具链支持，减少一部分重复和枯燥的劳动。现状...

tianyu 2019-08-16 10:42 评论0 收藏0
使用swagger 生成 Flask RESTful API

摘要：指定筛选条件选择合适的状态码应答中，需要带一个很重要的字段。返回结果针对不同操作，服务器向用户返回的结果应该符合以下规范。如果状态码是，就应该向用户返回出错信息。什么是 RESTful 什么是REST REST（英文：Representational State Transfer，又称具象状态传输）是Roy Thomas Fielding博士于2000年在他的博士论文中提出来的一种...

printempw 2019-07-30 14:18 评论0 收藏0