Flask-Docs自動生成Api文檔安裝使用教程

更新時間：2023年10月16日 11:47:33 作者：kwkwc

這篇文章主要為大家介紹了Flask-Docs自動生成Api文檔安裝使用教程,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進步,早日升職加薪

Flask-Docs

影響我寫文檔的原因可能是代碼和文檔分離，有時候?qū)懲甏a會忘記補文檔，而且不能及時查看，使用 Flask-Docs 可以解決我的問題，這個插件可以根據(jù)代碼注釋生成文檔頁面，代碼注釋改動文檔可以及時更新，而且支持離線文檔下載，支持在線調(diào)試。

Flask-Docs Flask Api 文檔自動生成插件

特性

根據(jù)代碼注釋自動生成文檔
支持離線 markdown 文檔下載
支持 Flask-RESTful
支持 Flask-RESTX
支持 flask.views.MethodView
支持在線調(diào)試

鏈接 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 函數(shù)名稱
# app.config["API_DOC_MEMBER_SUB_EXCLUDE"] = ["delete_data"]

如何書寫 markdown 格式文檔

@@@
在注釋結(jié)尾用 "@@@" 包含 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"})

調(diào)試器

以上就是Flask-Docs自動生成Api文檔安裝使用教程的詳細內(nèi)容，更多關于Flask-Docs生成Api文檔的資料請關注腳本之家其它相關文章！

您可能感興趣的文章:

Python之re操作方法(詳解)
下面小編就為大家?guī)硪黄狿ython之re操作方法(詳解)。小編覺得挺不錯的，現(xiàn)在就分享給大家，也給大家做個參考。一起跟隨小編過來看看吧
2017-06-06
使用Python繪制可愛的招財貓
招財貓,也被稱為“幸運貓”,是一種象征財富和好運的吉祥物,經(jīng)常出現(xiàn)在亞洲文化的商店、餐廳和家庭中,今天,我將帶你用 Python 和 matplotlib 庫從零開始繪制一只可愛的卡通招財貓,感興趣的小伙伴跟著小編一起來看看吧
2025-01-01
Python在圖片中添加文字的兩種方法
這篇文章主要給大家介紹了在Python在圖片中添加文字的兩種方法，分別是使用OpenCV和PIL這兩個方法實現(xiàn)，在實際應用中要在這兩種方法中擇優(yōu)使用。兩種方法都給出了詳細示例代碼，需要的朋友可以參考下。
2017-04-04
樹莓派升級python的具體步驟
在本篇文章里小編給大家整理的是關于樹莓派升級python的具體步驟，需要的朋友們可以參考下。
2020-07-07
Django入門優(yōu)缺點及環(huán)境搭建流程
這篇文章主要為大家介紹了Django入門優(yōu)缺點及環(huán)境搭建流程詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進步,早日升職加薪
2023-11-11
Python Matplotlib庫入門指南
這篇文章主要介紹了Python Matplotlib庫入門指南,本文講解了Matplotlib是什么,然后給出了Matplotlib基礎繪圖實例如繪制折線圖、繪制多線圖,并給出了圖例功能使用實例,需要的朋友可以參考下
2015-05-05
python在linux環(huán)境下安裝skimage的示例代碼
這篇文章主要介紹了python在linux環(huán)境下安裝skimage，本文通過實例代碼給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值,需要的朋友可以參考下
2020-10-10
python?管理系統(tǒng)實現(xiàn)mysql交互的示例代碼
這篇文章主要介紹了python?管理系統(tǒng)實現(xiàn)mysql交互,本文通過實例代碼圖文相結(jié)合給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下
2021-12-12
Python實現(xiàn)單個或批量文件移動的示例代碼
日常辦公和數(shù)據(jù)處理中,我們經(jīng)常需要將文件從一個目錄移動到另一個指定目錄,本文就來介紹一下Python實現(xiàn)單個或批量文件移動,具有一定的參考價值,感興趣的可以了解一下
2025-12-12
Python爬蟲之Selenium設置元素等待的方法
這篇文章主要介紹了Python爬蟲之Selenium設置元素等待的方法，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧
2020-12-12