beego api自動生成文件

必須設定在 routers/router.go 中，檔案的注釋，最頂部：

// @apiversion 1.0.0

// @title mobile api
// @description mobile has every tool to get any job done, so codename for the new mobile apis.
// @contact [email protected]
package routers

目前自動化文件只支援如下的寫法的解析，其他寫法函式不會自動解析，即 namespace+include 的寫法，而且只支援二級解析，一級版本號，二級分別表示應用模組

註解路由

router.go

func

init()
,),)
,)beego.
addnamespace
(ns)
}

controllers/user.go

在方法上邊加入注釋：// @router /login [post]

前端請求介面：/v1/user/login

type usercontroller struct

type result struct
// @title 登陸
// @description 使用者登陸介面
// @param phone formdata string false "手機號"
// @param id formdata string false "使用者id"
// @param nickname formdata string false "使用者名稱"
// @success 200  controllers.user.result
// @failure 404 介面未找到
// @failure 504 介面超時
// @router /login [post]
func
(this *usercontroller)
post()
this.data[
"json"]=
&result
this.
servejson()
}

首先是 cmscontroller 定義上面的注釋，這個是用來顯示這個模組的作用。接下來就是每乙個函式上面的注釋，這裡列出來支援的各種注釋：

@title

這個 api 所表達的含義，是乙個文字，空格之後的內容全部解析為 title

@description

這個 api 詳細的描述，是乙個文字，空格之後的內容全部解析為 description

@param

引數，表示需要傳遞到伺服器端的引數，有五列引數，使用空格或者 tab 分割，五個分別表示的含義如下

引數名引數型別，可以有的值是 formdata、query、path、body、header，formdata 表示是 post 請求的資料，query 表示帶在 url 之後的引數，path 表示請求路徑上得引數，例如上面例子裡面的 key，body 表示是乙個 raw 資料請求，header 表示帶在 header 資訊中得引數。

引數型別

是否必須

注釋

@success

成功返回給客戶端的資訊，三個引數，第乙個是 status code。第二個引數是返回的型別，必須使用 {} 包含，第三個是返回的物件或者字串資訊，如果是 型別，那麼 bee 工具在生成 docs 的時候會掃瞄對應的物件，這裡填寫的是想對你專案的目錄名和物件，例如 models.zdtproduct.productlist 就表示 /models/zdtproduct 目錄下的 productlist 物件。

三個引數必須通過空格分隔

@failure

失敗返回的資訊，包含兩個引數，使用空格分隔，第乙個表示 status code，第二個表示錯誤資訊

@router

路由資訊，包含兩個引數，使用空格分隔，第乙個是請求的路由位址，支援正則和自定義路由，和之前的路由規則一樣，第二個引數是支援的請求方法,放在 之中，如果有多個方法，那麼使用 , 分隔。

要使得文件工作，你需要做幾個事情，

main.go

if beego.bconfig.runmode ==

"dev"

開啟127.0.0.1:8080/swagger就可以檢視效果

字段描述

我們發現欄位都是optional的,而且沒有任何針對欄位的描述，其實我們可以在物件定義裡面增加如下的tag：

type sysuser struct

Django 自動生成文件

老是忘 記錄下 coreapi pip install coreapi rest framework from rest framework.documentation import include docs urls urlpatterns url api include docs urls ti...

使用Swagger自動生成文件

swagger 是乙個規範和完整的框架，用於生成 描述 呼叫和視覺化 restful 風格的 web 服務。springfox 的前身是 swagger springmvc，是乙個開源的 api doc 框架，可以將我們的 controller 的方法以文件的形式展現，基於 swagger。官網 第...

Sphinx python模組自動生成文件

安裝 pip install sphinx假設現在我們有乙個叫run.py的檔案，如下 run.py defrun name this is how we run param name name of people who runs print name,is running toctree max...