Flask-apidoc

影響我寫文檔的原因可能是代碼和文檔分離，有時候寫完代碼會忘記補文檔，而且不能及時查看，使用 Flask-apidoc 可以解決我的問題，這個插件可以根據代碼注釋生成文檔靜態頁面，靜態文件可以放在項目中或者直接用nginx部署。

安裝

1.安裝 node.js

sudo apt-get install nodejs sudo apt install nodejs-legacy sudo apt install npm

2.安裝 apidoc

npm install apidoc -g

3.Flask擴展包安裝

pip install flask-apidoc

4.添加擴展包到Flask項目

依賴環境：

flask>=0.10.1 flask_script>=2.0.5

manage.py項目啟動腳本配置

from views import app from flask_apidoc.commands import GenerateApiDoc from flask_script import Managermanager = Manager(app) manager.add_command('apidoc', GenerateApiDoc())if __name__ == "__main__":manager.run()

視圖函數文檔注釋說明示例

# -*- coding: utf-8 -*- from flask import Flask from flask_apidoc import ApiDocapp = Flask(__name__) doc = ApiDoc(app=app)@app.route('/users', methods=['POST']) def register():"""@api {post} /api/v1.0/users 注冊@apiVersion 1.0.0@apiName register_user@apiGroup Users@apiParam {String} mobile (必須) 用戶手機號@apiParam {String} password (必須) 用戶密碼@apiParam {String} sms_code (必須) 用戶短信驗證碼@apiParamExample {json} Request-Example:{mobile: "13970512239",password: "123456",sms_code: "907896"}@apiSuccess (回參) {int} user_id 用戶注冊id@apiSuccess (回參) {String} name 用戶昵稱@apiSuccess (回參) {String} mobile 用戶注冊手機號@apiSuccess (回參) {String} avatar 用戶頭像地址@apiSuccess (回參) {String} create_time 用戶創建時間@apiSuccessExample {json} Success-Response:{"errno":0,"errmsg":"注冊成功！","data": {"user_id": 1,"name": "lynnyq","mobile": "13813888888","avatar": "http://p3ifu3dwc.bkt.clouddn.com/FjuAwxmcCtiud_nOZ","create_time": "2010-1-1 12:12:12"}}@apiErrorExample {json} Error-Response:{"errno":4001,"errmsg":"數據庫查詢錯誤！"}"""pass

生成接口文檔命令

執行python manager.py apidoc生成文檔，如果這個命令報錯或者沒反應的話，可以使用下面這個：
apidoc -o static/docs（親測有效）
或者apidoc -o static/docs --debug顯示調試信息

*注：有人總結說，要給需要生成文檔的代碼文件頭部增加文檔字符串才行。如果文檔字符串沒有或者為空字符串的話，apidoc不起效。

接口文檔頁面效果示例

注釋中的@apiGroup可以用來給文檔分組

超強干貨來襲 云風專訪：近40年碼齡，通宵達旦的技術人生

總結

以上是生活随笔為你收集整理的使用 Flask-apidoc 自动生成 Api 文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。