脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 脚本专栏 → python → Flask-Docs生成Api文档

Flask-Docs自动生成Api文档安装使用教程

 更新时间：2023年10月16日 11:47:33   作者：kwkwc  
这篇文章主要为大家介绍了Flask-Docs自动生成Api文档安装使用教程,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪

Flask-Docs

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

Flask-Docs  Flask Api 文档自动生成插件

特性

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

链接 https://github.com/kwkwc/flas...

安装

pip3 install Flask-Docs

使用

from flask import Flask
from flask_docs import ApiDoc
app = Flask(__name__)
ApiDoc(
    app,
    title="Sample App",
    version="1.0.0",
    description="A simple app API",
)

配置

# 使用 CDN
# app.config["API_DOC_CDN"] = True
# 禁用文档页面
# app.config["API_DOC_ENABLE"] = False
# SHA256 加密的授权密码，例如这里是 admin
# echo -n admin | shasum -a 256
# app.config["API_DOC_PASSWORD_SHA2"] = "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
# 允许显示的方法
# 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"]
# 需要排除的子成员 Api 函数名称
# app.config["API_DOC_MEMBER_SUB_EXCLUDE"] = ["delete_data"]

如何书写 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"})

@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"})

完整代码

from flask import Blueprint, Flask, jsonify
from flask_docs import ApiDoc
app = Flask(__name__)
app.config["API_DOC_MEMBER"] = ["api", "platform"]
ApiDoc(
    app,
    title="Sample App",
    version="1.0.0",
    description="A simple app API",
)
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 import Flask
from flask_restful import Api, Resource
from flask_docs import ApiDoc
app = Flask(__name__)
restful_api = Api(app)
ApiDoc(
    app,
    title="Sample App Restful",
    version="1.0.0",
    description="A simple app restful 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")
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"})

调试器

以上就是Flask-Docs自动生成Api文档安装使用教程的详细内容，更多关于Flask-Docs生成Api文档的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

相关文章

  • 详解Python中的变量及其命名和打印

    详解Python中的变量及其命名和打印

    这篇文章主要介绍了Python中的变量及其命名和打印,是Python入门学习中的基础知识,需要的朋友可以参考下
    2016-03-03
  • numpy增加维度、删除维度的方法

    numpy增加维度、删除维度的方法

    本文主要介绍了numpy增加维度、删除维度的方法，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2023-02-02
  • Python/R语言分别实现斐波那契数列的示例详解

    Python/R语言分别实现斐波那契数列的示例详解

    这篇文章将通过两个小问题：年龄计算、斐波那契数列，带领大家深入浅出的理解两种语言的基本语法，并用以实际场景，需要的可以参考一下
    2022-03-03
  • python排序算法之希尔排序

    python排序算法之希尔排序

    这篇文章主要介绍了python排序算法之希尔排序,希尔排序，又叫“缩小增量排序”，是对插入排序进行优化后产生的一种排序算法,需要的朋友可以参考下
    2023-04-04
  • Python中文件路径的拼接的几种方法实例

    Python中文件路径的拼接的几种方法实例

    在Python开发中,文件路径的拼接是一个常见而且重要的任务,正确的路径拼接可以确保程序在不同平台上都能正常运行,本文将介绍Python中文件路径拼接的几种方式,包括使用os.path.join、os.path.join、pathlib库以及os.path.join
    2023-12-12
  • pycharm中创建sql文件及模板的过程

    pycharm中创建sql文件及模板的过程

    很多小伙伴刚开始使用pycharm时发现以前的老员工在使用pycharm创建sql文件时会自带文件头模板，例如时间、作者、版本、邮件等信息，这是怎么做到的呢，一起来看一下吧
    2022-07-07
  • 如何用python复制粘贴excel指定单元格(可保留格式)

    如何用python复制粘贴excel指定单元格(可保留格式)

    这篇文章主要给大家介绍了关于如何用python复制粘贴excel指定单元格(可保留格式)的相关资料,利用python操作excel非常方便,文中通过实例代码介绍的非常详细,需要的朋友可以参考下
    2023-07-07
  • Pandas检查dataFrame中的NaN实现

    Pandas检查dataFrame中的NaN实现

    本文主要介绍了Pandas检查dataFrame中的NaN实现，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2023-01-01
  • Python简直是万能的，这5大主要用途你一定要知道！（推荐）

    Python简直是万能的，这5大主要用途你一定要知道！（推荐）

    这篇文章主要介绍了Python主要用途，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2019-04-04
  • Pytorch 图像变换函数集合小结

    Pytorch 图像变换函数集合小结

    这篇文章主要介绍了Pytorch 图像变换函数集合小结，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2021-02-02

最新评论