自動為Flask寫的API生成幫助文檔

pakolagij 發布于2019-07-31 11:02 / 2294人閱讀

摘要：如果能自動生成一個幫助頁面那就好了。自動化幫助文檔假設我們的都是以的形式書寫的，那么最好把的完整列表就放在根目錄下面，比如這樣方法的實現主要依靠來獲取中所有的模板的實現接下來我們來文檔化每個具體的方法，最終的展示結果會是這樣的。

Flask是Python一個非常輕量的庫，可以讓你毫不費力地寫一個簡單的網站。如果你需要寫一些后臺API或者準備自動化測試數據時，Flask是一個非常不錯的選擇。

一個API例子

舉個例子，我們可以這樣寫幾個API，具體實現暫時略過：

# views/api.py

api = Blueprint("api", __name__)

@api.route("/get_todo", methods=["GET"])
def get_todo():
    """Get all todo tasks."""
    pass


@api.route("/add_todo", methods=["POST"])
def add_todo():
    """
    Add a todo task,  please post data in json format, e.g.

    data = {
              "name":"the title",
              "task":"the detail"
            }
    """
    pass


@api.route("/delete_todo", methods=["GET", "POST"])
def delete_todo():
    """Delete a todo task."""
    pass

一旦你的API完成，你可能需要和調用方溝通調用的細節，最好給一些例子。明明你已經在代碼里給所有方法都寫了注釋，難道還要再把這些注釋拿出來重新組織排版一下？

我猜你和我一樣，聽過這么一句話。

read the fucking manual!

可是誰會去翻代碼去看你的注釋呢，何況你的代碼他們還不一定能看到。如果能自動生成一個幫助頁面那就好了。

自動化API幫助文檔

假設我們的API都是以 http://127.0.0.1/api/* 的形式書寫的，那么最好把API的完整列表就放在根目錄下面，比如這樣：

view 方法的實現主要依靠 app.url_map 來獲取Flask中所有的API：

# views/api.py

def get_api_map():
    """Search API from rules, if match the pattern then we said it is API."""
    for rule in get_app().url_map.iter_rules():
        if re.search(r"/api/.+", str(rule)):
            yield str(rule), rule.endpoint


@api.route("/", methods=["GET"])
def index():
    """List all API to this page, api_map contains each api url + endpoint."""
    api_map = sorted(list(get_api_map()))
    index_url = url_for("main.index", _external=True)
    api_map = [(index_url + x[0][1:], x[1]) for x in api_map]
    return render_template("api_index.html", api_map=api_map)

模板的實現：

# templates/api_index.html

{% extends "./layout.html" %}

{% block title %}API Root{% endblock %}

{% block breadcrumb_nav %}
    Api Root
{% endblock %}

{% block page_header %}
    Api Root
{% endblock %}

{% block content_area %}
{
{% for i in api_map %}    "{{ i[0] }}"{{ ",
" if not loop.last }}{% endfor %}
}
{% endblock %}

接下來我們來文檔化每個具體的API方法，最終的展示結果會是這樣的。

view 方法的實現思路其實也很明確，我們可以通過 app.view_functions 這個字典找到每個API 的endpoint所綁定的方法，然后訪問方法的名字和文檔即可。

# views/main.py

main = Blueprint("main", __name__)


@main.route("/", methods=["GET"])
def index():
    """Redirect home page to docs page."""
    return redirect(url_for("api.index"))


@main.route("/docs/", methods=["GET"])
def docs(endpoint):
    """Document page for an endpoint."""
    api = {
        "endpoint": endpoint,
        "methods": [],
        "doc": "",
        "url": "",
        "name": ""
    }

    try:
        func = get_app().view_functions[endpoint]

        api["name"] = _get_api_name(func)
        api["doc"] = _get_api_doc(func)

        for rule in get_app().url_map.iter_rules():
            if rule.endpoint == endpoint:
                api["methods"] = ",".join(rule.methods)
                api["url"] = str(rule)

    except:
        api["doc"] = "Invalid api endpoint: "{}"!".format(endpoint)

    return render_template("api_docs.html", api=api)


def _get_api_name(func):
    """e.g. Convert "do_work" to "Do Work""""
    words = func.__name__.split("_")
    words = [w.capitalize() for w in words]
    return " ".join(words)


def _get_api_doc(func):
    if func.__doc__:
        return func.__doc__
    else:
        return "No doc found for this API!"

模板的實現：

{% extends "./layout.html" %}

{% block title %}API - {{ api["name"] }}{% endblock %}

{% block breadcrumb_nav %}
    Api Root
    {{ api["name"] }}
{% endblock %}

{% block page_header %}
    {{ api["name"] | upper }}
{% endblock %}

{% block content_area %}
Target:{{ api["url"] }}
Allow : {{ api["methods"] }}
Usage : {{ api["doc"] }}

{% endblock %}

GitHub項目地址

如果你想看完整的例子，可以到我的GitHub去拉一份代碼。

https://github.com/tobyqin/fl...

只需要三步就可以在你的機器上運行Demo：

cd /path/to/flask_api/doc
pip install -r requirements.txt
python main.py

如果你覺得Demo不錯，歡迎給個Star。有建議或者想法也可以拿來討論。

關于作者：

Toby Qin, Python 技術愛好者，目前從事測試開發相關工作，轉載請注明原文出處。

歡迎關注我的博客 https://betacat.online，你可以到我的公眾號中去當吃瓜群眾。

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/44541.html

Python使用pywebview開發設計桌面應用的全流程

　　當運用桌面應用程序時,有沒有有一瞬間,想學習下桌面應用程序開發設計?接下來本文關鍵為大家介紹了有關Python使用pywebview開發設計桌面應用的資料,必須的小伙伴可以借鑒一下　　序言　　平時用過Eel做出來的桌面應用感覺就已經夠屌了,不過因為Eel是啟用Chrome,常常出現一些小毛病,例如窗口大小設定后有的時候不起作用,右鍵新建菜單沒法禁止使用(一眼就能看出來是一個web).并且試了用...

89542767 2023-01-06 14:46 評論0 收藏0
使用 Flask-Docs 自動生成 Api 文檔

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

鄒強 2019-07-30 17:06 評論0 收藏0
Flask Api 文檔管理與 Swagger 上手

摘要：眾數周知，文檔的編寫和整理工作將花費巨大精力甚至不亞于代碼的編寫，因此在時間緊任務重的情況下，文檔是首先被忽略的工作。是一款非常流行的文檔管理交互工具，適用于在團隊中的管理，以及服務組件對接。而我們目前需要的是獲取文檔或文件。本文最先發布在博客：https://blog.ihypo.net/152551... Flask 是一個以自由度高、靈活性強著稱的 Python Web 框架...

Scholer 2019-07-30 16:29 評論0 收藏0
flask 源碼解析：簡介

摘要：簡介官網上對它的定位是一個微開發框架。另外一個必須理解的概念是，簡單來說就是一套和框架應用之間的協議。功能比較豐富，支持解析自動防止攻擊繼承變量過濾器流程邏輯支持代碼邏輯集成等等。那么，從下一篇文章，我們就正式開始源碼之旅了文章屬于作者原創，原文發布在個人博客。 flask 簡介 Flask 官網上對它的定位是一個微 python web 開發框架。 Flask is a micro...

megatron 2019-07-25 11:23 評論0 收藏0
使用swagger 生成 Flask RESTful API

摘要：指定篩選條件選擇合適的狀態碼應答中，需要帶一個很重要的字段。返回結果針對不同操作，服務器向用戶返回的結果應該符合以下規范。如果狀態碼是，就應該向用戶返回出錯信息。什么是 RESTful 什么是REST REST（英文：Representational State Transfer，又稱具象狀態傳輸）是Roy Thomas Fielding博士于2000年在他的博士論文中提出來的一種...

printempw 2019-07-30 14:18 評論0 收藏0