python⽣成api⽂档_API⽂档⾃动⽣成⼯具apiDoc简介
随着移动客户端的流⾏，后端系统需开放越来越多的API来供客户端使⽤。API⽂档的编写和管理是⼀个挑战，随着API不断变化，⽂档必须及时更新，但编写⽂档也是个不⼩的负担。⼀个⽐较好的做法(Best Practice)，就是将⽂档放在代码⾥，开发⼈员编写代码时同时修改⽂档。然后通过⼯具从代码中抽出⽂档，并⽣成⽅便⽤户阅读的格式。此类⼯具早已存在，⽐如Java中的javadoc。这⾥我们要介绍⼀个⾮常轻量级的，适⽤于⼏乎所有流⾏语⾔的，针对Restful API的⽂档⾃动⽣成⼯具－apiDoc。
⼯具安装
和所有的技术介绍⼀样，我们先从安装开始。apiDoc基于NodeJS实现，所以你需先有NodeJS及NPM环境。然后通过：
$ npm install apidoc -g
全局安装apiDoc。之后，你就可以执⾏下⾯的命令来⽣成⽂档：
$ apidoc -i src -o dest
该命令从当前⼯作⽬录的”src”⼦⽬录下读取所有代码⽂件，并从中抽取apiDoc的⽂档注释，然后⽣成HTML格式的⽂档，并保存
在”dest”⼦⽬录下。执⾏完后，⽤户就可以打开”dest”下的”index.html”来阅读⽂档。
“apidoc”命令⽀持许多参数，常⽤的有：
-t template
根据”template”⼦⽬录下的模板⽣成⽂档，缺省时采⽤apiDoc的默认模板。⽤户也可以编写⾃⼰的模板。关于模板的细节，本⽂不多介绍了。
-f ".*\\.py$"
只解析Python代码。-f后的参数按正则匹配，可以设置多个-f参数。
-h
显⽰该命令帮助信息。
配置⽂件
运⾏apidoc前，你需先有⼀个配置⽂件，放在代码根⽬录下（如上例中的src⽬录），取名为”apidoc.json”。下⾯是⼀个标准配置⽂件的例⼦：
{
"name": "User API Document",
"version": "0.1.0",
"description": "A sample of User API document generated from apiDoc",
"title": "User API",
"url" : "localhost:5000",
"sampleUrl": "localhost:5000",
"header": {
"title": "Overview",
"filename": "header.md"
},
"footer": {
"title": "Copyright",
"filename": "footer.md"
},
"template": {
"withCompare": true,
"withGenerator": true
}
}
简单介绍下：
name, version, description
这三个配置项的内容会显⽰在⽣成⽂档的最上⽅，其中name即整个⽂档的⼤标题。
title
⽹页的标题，显⽰在浏览器标签上。
url
⽂档中每个API地址的前缀。
sampleUrl
当有此项时，每个API⽂档的最后会有Sample Request测试部分。该配置项是测试API地址的前缀。
header, footer
页⾯的头和尾。当多个页⾯都有相同的头和尾时，这个配置项就⾮常有⽤。⼦配置项中
title
页⾯左边菜单栏中显⽰的标题。
filename
指向页头或页尾的模板⽂件，apiDoc使⽤的是Markdown⽂件。
template
withCompare
⽣成的⽂档有版本⽐较功能。后⾯会介绍。默认为”true”。
withGenerator
⽣成的⽂档页尾带有⼀段⽂字，表⽰这个⽂档是由apiDoc⽣成的，加上这个代表对作者的尊重吧。默认为”true”。让我们简单写下页头和页尾的Markdown⽂件，并将它们同”apidoc.json”放在⼀起，即”src”⽬录下。header.md
## Overview
Below is the API doc of User APIs.
footer.md
API⽂档注释
接下来，我们就要介绍最主要的部分了，就是API代码上的⽂档注释。这个注释⼀般会加在对外开放的API函数上⽅。这⾥，我们要⽤到本博客⽂章Flask扩展系列(⼀)–Restful中的例⼦。这个例⼦是Python代码写的，其提供了user对象的增删改查API。Python的注释是由三个双引号"""来包括，如果是Java, JS或PHP，则⽤/** */来包括。我们就拿单个user的GET⽅法来举例⼦：
class User(Resource):
"""
@api {get} /users/:user_id Request User Information
@apiVersion 0.1.0
@apiName GetUser
@apiGroup User
@apiPermission admin
@apiDescription API to get the user information.
@apiExample Example usage:
@apiParam {Number} user_id The user's unique ID.
@apiSuccess {String} name Name of the User.
@apiSuccessExample {json} Success-Response:
HTTP/1.1 200 OK
{
"name": "Tom"
}
@apiError UserNotFound The user_id of the User was not found.
@apiErrorExample {json} Error-Response:
HTTP/1.1 404 Not Found
{
"error": "UserNotFound",
"message": "User {user_id} doesn't exist"
}
"""
def get(self, user_id):
abort_if_not_exist(user_id)
return USER_LIST[user_id]
可以看到，⽂档注释主要是由⼀系列以@符号开头的参数组成，让我们来逐⼀介绍：
@api {get} /users/:user_id Request User Informationpython官方文档中文版
最主要的参数，{get}定义了HTTP请求是GET，API地址是/users/:user_id，⽂档中API的名称是Request User Information。
@apiVersion 0.1.0
API的版本号，默认显⽰在API名称的右⽅。该参数可⽤来在不同的版本之间做⽐较，后⾯会介绍。
@apiName GetUser
API名称，不影响⽂档。
@apiGroup User
API分组名，⽂档内容中和菜单栏中同⼀组的API会在⼀同显⽰，⽅便阅读。
@apiPermission admin
API的访问权限，⽂档中默认会API地址下⾯显⽰。没有权限要求的话，此项可以省略。
@apiDescription API to get the user information.
API的详细描述，默认显⽰在API名称的下⽅。
@apiExample Example usage:
API调⽤⽰例，该参数的下⼀⾏就是⽰例的内容，直到有空⾏结束。可以定义多个@apiExample，默认在⽂档中会以标签形式列出，标签名就是”Example usage:“。
@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍，”{Number}“定义了字段类型，”user_id”是字段名称，后⾯则是字段描述。可以定义多个@apiParam字段。
@apiSuccess {String} name Name of the User.
API成功后返回的字段，如同@apiParam，”{String}“定义了字段类型，”name”是返回字段名称，后⾯则是字段描述。可以定义多个@apiSuccess字段。
@apiSuccessExample {json} Success-Response:
显⽰⼀个API成功返回后Response响应的⽰例，”{json}“代表响应体是JSON类型。该参数的下⾏就是响应体内容，直到有空⾏结束。可以定义多个@apiSuccessExample，默认在⽂档中会以标签形式列出，标签名就是”Success-Response:“。
@apiError UserNotFound User was not found.
API发⽣错误后的返回，”UserNotFound”是错误名称，后⾯则是错误描述。可以定义多个错误返回。
@apiErrorExample {json} Error-Response:
显⽰⼀个API错误返回后Response响应的⽰例，”{json}“代表响应体是JSON类型。该参数的下⾏就是响应体内容，直到有空⾏结束。可以定义多个@apiErrorExample，默认在⽂档中会以标签形式列出，标签名就是”Error-Response:“。
⽂档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后，此参数即可省去，除⾮这个API的测试URL⽐较特殊，需特别指定。
好，现在让我们把这个代码放在”src”⽬录下，然后执⾏命令
$ apidoc -i src -o dest
打开”dest”⽬录下的”index.html”⽂件，看看我们的API⽂档，是不是很不错？要不动动⼿，把这个代码的其他API⽂档注释⼀起加上吧？
参数信息重⽤
很多时候，不同的API有着相同的⽂档内容，⽐如相同的成功响应⽰例，或者相同的错误返回。当API⾮常多时，⼀个变化需要改动多处的API⽂档，很⿇烦。能不能像写C代码⼀样，定义⼀个宏，然后在API⽂档注释中引⽤这个宏呢？答案是有，在apiDoc中，这叫继承(inherit)。⾸先，你要在源代码注释中⽤@apiDefine定义这个宏。⽐如，下⾯的注释，就是把上例中UserNotFound错误及其响应⽰例定义在⼀个名叫UserNotFoundError的宏中。此后，所有需要使⽤这段⽂档的地⽅，就通过@apiUse UserNotFoundError引⼊这个宏即可。
class User(Resource):
"""
@apiDefine UserNotFoundError
@apiError UserNotFound The user_id of the User was not found.
@apiErrorExample {json} Error-Response:
HTTP/1.1 404 Not Found
{
"error": "UserNotFound",
"message": "User {user_id} doesn't exist"
}
"""
"""
@api {get} /users/:user_id Request User Information
...
@apiUse UserNotFoundError
"""
def get(self, user_id):
# Code here
"""
@api {delete} /users/:user_id Delete a User
...
@apiUse UserNotFoundError
"""
def delete(self, user_id):
# Code here
当宏定义⽐较多时，怎么管理呢？我们可以把宏定义挪到代码以外去。让我们在”src”根⽬录下建⽴⼀个⽂件”_apidoc.py”。然后把上⾯UserNotFoundError的定义移到这个⽂件中。
"""
@apiDefine UserNotFoundError
@apiVersion 0.1.0
@apiError UserNotFound The user_id of the User was not found.
@apiErrorExample {json} Error-Response:
HTTP/1.1 404 Not Found
{
"error": "UserNotFound",
"message": "User {user_id} does not exist"

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。