apidoc学习(接口文档定义取代word)
阅读原文时间:2023年07月10日阅读:1

apidoc的安装,参考:https://blog.csdn.net/qq_36386771/article/details/82149848

生产文档,需要先编写一个apidoc.json对接口文档进行基本说明,在编写一些接口定义文档(采用js),然后运行命令,生成对于的html网页

demo案例:目录结构:

xxxx/apidoc_demo/apidoc.json 接口文档的总说明
xxxx/apidoc_dem/myapp/demo.js 接口文档具体接口的定义
xxxx/apidoc_dem/apidoc/ 用于存放生成的html文件
在xxxx/apidoc_demo/目录下执行命令 >> apidoc -i myapp/ -o apidoc/

新建apidoc.json

{
"name": "p1app_v2",
"description": "P1APP二期的接口文档",
"version": "0.0.1",
"title": "p1app_v2_doc",
"url": "https://localhost:8010/p1app_v2"
}

新建一个demo.js

/\*\*  
 \* @apiDefine Index 首页  
 \*/

    /\*\*  
     \* @api {post} /Index/getVip 获取vip列表   页面加载时自动获取  
     \* @apiName getVip  
     \* @apiGroup Index  
     \* @apiParam {string} req1 请求值  
     \* @apiSuccess (200) {Object\[\]} profiles List of user profiles.  
  \* @apiSuccess (200) {Number}   profiles.age   Users age.  
  \* @apiSuccess (200) {String}   profiles.image Avatar-Image.  
  \* @apiSuccess (201) {String}   failed Avatar-Image.  
     \* @apiSuccessExample {json} Success-Response:  
     \* {  
     \*   res1:"test"  
     \* }  
     \*/

    /\*\*  
     \* @api {get} /Index/getWeather 获取指定日期的逐小时气象数据信息  
     \* @apiName getWeather  
     \* @apiGroup Index  
     \* @apiDescription 根据传递的行政区编码,获取所在城市的信息,得到城市对应的气象数据。  
     \* @apiParam {String} \[date\] 日期,格式yyyy-MM-dd,不传,默认为当日  
     \* @apiParam {String} region\_code 行政区编码,如"500244"  
     \* @apiParam {String="hour","day","week","month","year"} data\_type 数据类型  
     \* @apiParam {Number=10,20} num 记录最大返回条数  
     \* @apiParam {String{5...10}} strlen 字符串长度限制  
     \* @apiParam {Number{5-10}} num\_range 数字范围  
     \* @apiParam {String{5-10}} str\_range 字符串范围  
     \* @apiVersion 0.0.1  
     \* @apiSuccess {JsonObject} result JsonObject对象  
     \* @apiSuccessExample Success-Response:  

{
"code": 0,
"msg": "success",
"data":[
{
"date": "2019-05-30 01",
"humidity": 0.97
},
{
"date": "2019-05-30 02",
"humidity": 0.98
}
]
}
*/

效果图如下:

apidoc的注解说明:

@api {get} /users/:user_id Request User Information
最主要的参数,”{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:”。

@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后,此参数即可省去,除非这个API的测试URL比较特殊,需特别指定。

使用js编写,这些注解都写在注释中,上面的内容引用自:https://www.jianshu.com/p/d324810d694d

参数定义说明:参考https://blog.csdn.net/qq_14824885/article/details/87793476#apiParam_251

apidoc使用中文说明:https://blog.csdn.net/qq_14824885/article/details/87793476

apidoc使用英文说明(官方文档):http://apidocjs.com/

针对版本变更以及对比,待继续学习…….

手机扫一扫

移动阅读更方便

阿里云服务器
腾讯云服务器
七牛云服务器

你可能感兴趣的文章