Apidoc簡介
apidoc是一款可以根據源代碼中的註釋直接自動生成api接口文檔的工具。生成一個doc文件夾，包含了渲染的css，fonts等, python中註釋的方法爲
"""
@apidoc
"""
安裝及應用
安裝前，需要先更新到最新的node.js, 使用npm執行命令:
npm install apidoc -g
安裝好後，在要生成接口文檔的源碼根目錄下， 建立一個配置文檔apidoc.json， 這個文檔主要包含一些項目的描述信息，比如標題、簡述、版本等，你也可以加入一些可選的配置項，比如頁眉、頁腳、模板等。
==ps： 如果未檢測到apidoc.json， 導出文檔會報錯~==
{
"name": "項目名稱",
"version": "版本",
"description": "簡述",
"title": "瀏覽器標題",
"url" : "api路徑前綴，例：https://api.kafka.com",
"apiSampleRequest"(選填): "導出的文檔中每一個接口都會包含模擬接口請求的form表單(測試接口)",
"header.title"(選填): "頁眉標題"，
"header.filename"(選填): "頁眉文件名",
"footer.title" (選填): "頁腳標題"，
"footer.filename"(選填): "頁腳文件名"，
"order"(選填): "排序"
}
導出文檔時, 在根目錄執行命令即可
apidoc -i (要生成文檔的文件) -o (文檔生成目標文件中)
eg: apidoc -i qhd_convert_fields\models -o .\apidoc
Python中apidoc註釋參數
常規註釋詳解:
def Apidoc()
"""
@api {請求類型} 路徑(根路徑) 接口標題,
----------eg:-------------
@api {get, post} /test_consumer_button 測試kafka消費
@apiVersion 版本號
@apiName 接口名稱
@apiDescription 接口的描述
@apiGroup 所屬分組, 例如一個模塊爲一個分組,那模塊下所有的接口分組都是同一個
@apiPermission 允許訪問該接口的角色名稱(唯一)
@apiSampleRequest 如果apidoc.json中有設置apiSampleRequest, 在接口註釋中再寫則意味着覆蓋 ,
如果apidic.json中沒有設置, 則給當前接口單獨設置模擬接口
@apiSampleRequest off意爲關閉當前接口測試功能
請求參數: 固定格式
@apiParam (所屬組(有默認)) {字段類型} 字段名([選填],[=默認值]) 字段描述
----------eg:-------------
@apiParam {String} ip=10.1.254.107 有默認值且必填的IP字段
@apiParam {Number} [port=9092] 有默認值且選填的端口
@apiParam {String} topic_name 必填項topic名
請求體參數示例:固定格式
@apiParamExample [{請求內容格式}] [請求示例標題]
example 請求示例詳情(兼容多行)
----------eg:-------------
@apiParamExample {json} Request-test:
{
'name': test_kafka,
'IP': 127.0.0.1,
'Port': 8868,
'thread_num': 5,
}
接口成功返回參數: 固定格式
@apiSuccess [(group)] [{type}] field [description]
----------eg:-------------
@apiSuccess {bool} msg successful # group默認值:Success200
@apiSuccess (200) {bool} msg successful
@apiSuccess {Number} self.age 回參爲數值
@apiSuccess {Object} self.kafka_msg 回參爲對象
@apiSuccess {Object[]} self 回參爲數組
返回成功示例
@apiSuccessExample [{type}] [title]
example
----------eg:-------------
@apiSuccessExample {json} Success-Response:
{
'msg': 'Connect successful',
'age':self.age,
'topic_list': [
'real_timeStationTopic',
'unexpectedStationTopic']
}
"""
print('This is a demo')
完整示例:
def apidoc():
"""
@api {get, post} /test_producer_button 測試kafka生產
@apiVersion 1.0.0
@apiName 測試kafka生產
@apiDescription 測試傳入的數據根據topic是否可以生產消息, 傳入的數據需要手動填入
@apiGroup Lty_kafka_gateway
@apiSampleRequest off
@apiParam {String} ip=10.1.254.107 kafka的IP地址
@apiParam {Number} [port=9092] kafka的端口
@apiParam {String} topic_name 主題名
@apiParam {String} [another] 其他的根據對應topic,在鍵入消息欄填入數據, 判
斷是否可以生產成功數據
@apiParamExample {json} Request-Example:
{
"IP": 127.0.0.1,
"Port": 8868,
"topic_name": test_kafka,
"line_id": 12,
"gprs_id": 456,
}
@apiSuccess {bool} msg successful
@apiSuccess {Number} age successful age
@apiSuccess {Object} self.kafka_msg successful msg
@apiSuccess {Object[]} self self msg
@apiSuccessExample {json} Success-Response:
{
"msg": "Connect successful",
"age":self.age,
"kafka_msg":self.kafka_msg,
"self":self,
"topic_list": [
"real_timeStationTopic",
"unexpectedStationTopic",
"BusInspect_Topic",
"ITS_Topic_ScheduingPlan"]
}
"""
註釋詳解:
1、 @api
【必填字段】否則，apidoc會忽略該條註釋
| 參數 | 必填 | 描述 |
|---|---|---|
| method | yes | 請求類型:DELETE, GET, POST, PUT, ...更多 |
| path | yes | 請求路徑 |
| title | no | 接口標題 |
例：
"""
@api {get} /user/:id
@api {get, post} /test_consumer_button 測試kafka消費
"""
2、 @apiDefine
定義註釋模塊(類似於代碼中定義一個常量)，對於一些通用可複用的註釋模塊(例如:接口錯誤響應模塊),只需要在源代碼中定義一次，便可以在其他註釋模塊中隨便引用，最後在文檔導出時會自動替換所引用的註釋模塊，定義之後您可以通過@apiUse來引入所定義的註釋模塊。(注:可以同時使用@apiVersion來定義註釋模塊的版本)
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| name | yes | 註釋模塊名稱(唯一)，不同@apiVersion可以定義相同名稱的註釋模塊 |
| title | no | 註釋模塊標題 |
| description | no | 註釋模塊詳細描述(詳細描述另起一行，可包含多行) |
3、@apiDeprecated
標註一個接口已經被棄用
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| text | yes | 多行文字描述 |
例：
"""
@apiDeprecated Why abandon
"""
4、@apiDescription
api接口的詳細描述
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| text | yes | 多行文字描述 |
例：
"""
@api {get} /user/:id
@apiDescription 測試傳入的數據根據topic是否可以生產消息
"""
5、@apiError
錯誤返回參數
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| (group) | no | 所有的參數都會通過這個參數進行分組，如果未設置，默認值爲Error 4xx |
| {type} | no | 返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]}) |
| field | yes | 返回id |
| description | no | 參數描述 |
例：
"""
@api {get} /user/:id
@apiError UserNotFound The id of the User was not found.
"""
6、@apiErrorExample
接口錯誤返回示例(格式化輸出)
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| type | no | 響應類型 |
| title | no | 示例標題 |
| example | yes | 示例詳情(兼容多行) |
例:
"""
@api {get} /user/:id
@apiErrorExample {json} Error-Response:
HTTP/1.1 404 Not Found
{
"error": "UserNotFound"
}
"""
7、@apiExample
接口方式請求示例
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| type | no | 請求內容格式 |
| title | yes | 示例標題 |
| example | yes | 示例詳情(兼容多行) |
8、@apiGroup
定義接口所屬的接口組，雖然接口定義裏不需要這個參數，但是您應該在每個接口註釋裏都添加這個參數，因爲導出的接口文檔會以接口組的形式導航展示。
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| type | no | 請求內容格式 |
例：
"""
@api {get} /user/:id
@apiGroup User
"""
9、@apiHeader
描述接口請求頭部需要的參數(功能類似@apiParam)
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| (group) | no | 所有的參數都會以該參數值進行分組(默認Parameter) |
| {type} | no | 返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]}) |
| field | yes | 參數名稱(定義該頭部參數爲可選) |
| [field] | yes | 參數名稱(定義該頭部參數爲可選) |
| =defaultValue | no | 參數默認值 |
| description | no | 參數描述 |
例：
"""
@api {get} /user/:id
@apiHeader {String} access-key Users unique access-key.
"""
10、@apiHeaderExample
請求頭部參數示例
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| type | no | 請求內容格式 |
| title | no | 請求示例標題 |
| example | yes | 請求示例詳情(兼容多行) |
例:
"""
@api {get} /user/:id
@apiHeaderExample {json} Header-Example:
{
"Accept-Encoding": "Accept-Encoding: gzip, deflate"
}
"""
11、@apiIgnore
如果你需要使用該參數，請把它放到註釋塊的最前面。如果設置了該參數，那麼該註釋模塊將不會被解析(當有些接口還未完成或未投入使用時，可以使用該字段)
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| hint | no | 描接口忽略原因描述 |
12、@apiName
接口名稱，每一個接口註釋裏都應該添加該字段，在導出的接口文檔裏會已該字段值作爲導航子標題，如果兩個接口的@apiVersion和@apiName一樣，那麼有一個接口的註釋將會被覆蓋(接口文檔裏不會展示)
參數列表：
| 參數 | 必填 | 描述 |
|---|---|---|
| name | yes | 接口名稱(相同接口版本下所有接口名稱應該是唯一的) |
13、@apiParam
接口請求體參數
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| (group) | no | 所有的參數都會以該參數值進行分組(默認Parameter) |
| {type} | no | 返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]}) |
| {type{size}} | no | 返回類型,同時定義參數的範圍{string{..5}}意爲字符串長度不超過5{string{2..5}}意爲字符串長度介於25之間<br/>`{number{100-999}}`意爲數值介於100999之間 |
| {type=allowedValues} | no | 參數可選值{string="small"}意爲字符串僅允許值爲"small"{string="small","huge"}意爲字符串允許值爲"small"、"huge"{number=1,2,3,99}意爲數值允許值爲1、2、3、99{string {..5}="small","huge"意爲字符串最大長度爲5並且值允許爲:"small"、"huge" |
| field | yes | 參數名稱(定義該請求體參數爲必填) |
| [field] | yes | 參數名稱(定義該請求體參數爲可選) |
| =defaultValue | no | 參數默認值 |
| description | no | 參數描述 |
14、@apiParamExample
請求體參數示例
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| type | no | 請求內容格式 |
| title | no | 請求示例標題 |
| example | yes | 請求示例詳情(兼容多行) |
例：
"""
@api {get} /user/:id
@apiParamExample {json} Request-Example:
{
"id": 4711
}
"""
15、@apiPermission
允許訪問該接口的角色名稱
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| name | yes | 允許訪問的角色名稱(唯一) |
例：
"""
@api {get} /user/:id
@apiPermission admin
"""
16、@apiPrivate
定義私有接口，對於定義爲私有的接口，可以在生成接口文檔的時候，通過在命令行中設置參數 --private false|true來決定導出的文檔中是否包含私有接口
17、@apiSampleRequest
設置了該參數後，導出的html接口文檔中會包含模擬接口請求的form表單；如果在配置文件apidoc.json中設置了參數sampleUrl,那麼導出的文檔中每一個接口都會包含模擬接口請求的form表單，如果既設置了sampleUrl參數，同時也不希望當前這個接口不包含模擬接口請求的form表單，可以使用@apiSampleRequest off來關閉。
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| url | yes | 模擬接口請求的url@apiSampleRequest http://www.example.com意爲覆蓋apidoc.json中的sampleUrl參數@apiSampleRequest off意爲關閉接口測試功能 |
18、 @apiSuccess
@apiSuccess [(group)] [{type}] field [description]
接口成功返回參數
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| (group) | no | 所有的參數都會以該參數值進行分組,默認值:Success 200 |
| {type} | no | 返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]}) |
| field | yes | 返回值(返回成功碼) |
| =defaultValue | no | 參數默認值 |
| description | no | 參數描述 |
例:
"""
@api {get} /user/:id
@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname Lastname of the User.
"""
包含(group):
"""
@api {get} /user/:id
@apiSuccess (200) {String} firstname Firstname of the User.
@apiSuccess (200) {String} lastname Lastname of the User.
"""
返回參數中有對象:
"""
@api {get} /user/:id
@apiSuccess {Boolean} active Specify if the account is active.
@apiSuccess {Object} profile User profile information.
@apiSuccess {Number} profile.age Users age.
@apiSuccess {String} profile.image Avatar-Image.
"""
返回參數中有數組：
"""
@api {get} /users
@apiSuccess {Object[]} profiles List of user profiles.
@apiSuccess {Number} profiles.age Users age.
@apiSuccess {String} profiles.image Avatar-Image.
"""
19、 @apiSuccessExample
@apiSuccessExample [{type}] [title]
example
返回成功示例
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| type | no | 返回內容格式 |
| title | no | 返回示例標題 |
| example | yes | 返回示例詳情(兼容多行) |
例：
"""
@api {get} /user/:id
@apiSuccessExample {json} Success-Response:
HTTP/1.1 200 OK
{
"firstname": "John",
"lastname": "Doe"
}
"""
20、@apiUse
@apiUse name
引入註釋模塊,就是前面提到的@apiDefine定義的註釋塊，如果當前模塊定義了@apiVersion,那麼版本相同或版本最近的註釋模塊會被引入
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| name | yes | 引入註釋模塊的名稱 |
例:
"""
@apiDefine MySuccess
@apiSuccess {string} firstname The users firstname.
@apiSuccess {number} age The users age.
"""
"""
@api {get} /user/:id
@apiUse MySuccess
"""
21、 @apiVersion
@apiVersion version
定義接口/註釋模塊版本
參數列表:
| 參數 | 必填 | 描述 |
|---|---|---|
| version | yes | 版本號(支持APR版本規則:major.minor.patch) |
例:
"""
@api {get} /user/:id
@apiVersion 1.6.2
"""
原文參考: [apidoc官方文檔(翻譯)](https://www.jianshu.com/p/9353d5cc1ef8)
原文參考: [apidoc官方文檔](http://apidocjs.com/#param-api-define)