Django项目生成api文档 之 apidoc（3）

APIDOC 之 Pythondoc 样式

apiDoc通过源代码中的API注释创建文档。

apiDoc参数

@apiDefine

 @apiDefine name 
 [title] [description]
 [title] [description]
 ....

Tips：类似自定义函数的用法，先定义内容，然后通过@apiUse name调用。

示例：

# 定义模块 LoginParam
"""
@apiDefine LoginParam
@apiParam {String} username Your e-mail-address.
@apiParam {String} password Your password.
"""
# 定义模块 UserParam
"""
@apiDefine UserParam
@apiParam {String} firstname Your firstname.
@apiParam {String} lastname  Your lastname.
@apiParam {Date}   birthday  Your birthday.
"""
# 定义模块UserNotFoundError
"""
@apiDefine UserNotFoundError
@apiError UserNotFound The id of the User was not found.
@apiErrorExample Error-Response:
     HTTP/1.1 404 Not Found
     {
       "error": "UserNotFound"
     }
"""
# 调用 LoginParam 和 UserParam 模块
"""
@api {GET} /account/register Register a new user.
@apiUse LoginParam
@apiUse UserParam
@apiParam {Boolean} terms Checkbox to accept the terms.
@apiUse UserNotFoundError
"""

@api

定义请求方式 （GET/POST/PUT 等）和 请求路径 。

 @api {method} path [title]

名称	描述
method	参数值为请求方式名：GET/POST/DELETE/PUT/……
path	请求路径
title	该api的简短标题（用于导航和文章标题）

注意：

1. 如果没有该指示符@api，则apiDoc解析器将忽略文档记录块。
2. 唯一的例外是由定义的文档块 @apiDefine

示例:

"""
@api {post} /modules/indexShow 获取modules列表信息
"""

"""
@api {get} /user/:id Users unique ID.
"""

未完待续…

---

[参考文档]
[1]：https://apidocjs.com/