apidoc学习(接口文档定义取代word)
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/
针对版本变更以及对比,待继续学习.......
apidoc学习(接口文档定义取代word)的更多相关文章
- flask + apidoc 生成接口文档(附加一个坑)
具体使用方法见这里 https://blog.csdn.net/lynnyq/article/details/79254290 挺详细的,我就不抄了. 重点是一个坑: 执行 python manage ...
- apidoc接口文档的快速生成
官方文档连接:http://apidocjs.com/#demo apidoc是一个轻量级的在线REST接口文档生成系统,支持多种主流语言,包括Java.C.C#.PHP和Javascript等.使用 ...
- 接口文档神器之apidoc
//@desn:apidoc linux环境 windows环境使用 //@desn:码字不宜,转载请注明出处 //@author:张慧源 <turing_zhy@163.com> / ...
- web接口文档apidoc的使用
1.安装 npm install apidoc -g 2.新建src文件夹,里面放2个文件,test.js和apidoc.json 3.test.js /** * @api {get} /query_ ...
- 在sublime3中docblockr插件配置apidoc接口文档注释模板
写在前面: 将进行3个步骤配置 1.在sublime3中安装插件docblockr,可以参考http://www.cnblogs.com/jiangxiaobo/p/8327709.html 2.安装 ...
- Spring MVC学习总结(9)——Spring MVC整合swagger自动生成api接口文档
Swagger 号称:世界最流行的API框架,官网:http://swagger.io/,Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总 ...
- 快速根据注释生成接口文档网页工具——Apidoc的使用教程
1,安装Node.js的npm工具环境: 如有不懂,请看我的博客:“https://blog.csdn.net/sinat_28371057/article/details/81612661“ 2,n ...
- apidoc 接口文档系统
代码未动,文档先行.apidoc可以方便地维护接口文档.模拟响应数据.前后端分离.导出PDF文档. 特性说明 可视化编辑:支持表单界面编辑接口,不必手动编辑swagger.json 接口模拟响应:支持 ...
- FastAPI 学习之路(二十)接口文档配置相关
系列文章: FastAPI 学习之路(一)fastapi--高性能web开发框架 FastAPI 学习之路(二) FastAPI 学习之路(三) FastAPI 学习之路(四) FastAPI 学习之 ...
随机推荐
- python之 socketserver模块的使用
在我们正常的使用socket模块来写一个server的程序就会显得比较的复杂通常一般流程为 1.生成socket实例对象 2.绑定地址 3.开始监听 4.接收数据 一般demo为 # 服务器 impo ...
- Blazor入手教程(一)前言
Blazor入手教程(一)前言 结论 最近在学习blazor.得出了这么一个结论: Blazor是一门很值得学习的技术,未来.net下将会有相当多的 web应用使用blazor开发.十分看好这一技术, ...
- 软链接mongo
ln -s /usr/local/mongodb/bin/mongo /usr/bin/mongo
- vue中插值表达式中时间转换yyyy-MM-dd HH:mm:ss
vue插值表达式中将时间转换两种方式:一.定义方法 <div id="app">当前实时时间:{{dateFormat(date)}}</div> //时间 ...
- 思维导图iMindMap可以在哪些领域应用
生活工作中你常常会遇到许多力所不能及的事情,感到无奈.茫然,这时候你急需一个帮手来帮你打破困境,思维导图就是这样的救世主,至于它有哪些力所能及的事情就是下面小编要跟你讲的. 你是否经常遇到过这样的情况 ...
- pdfFactory如何设置限制打印和浏览文档权限
当我们进行私密文件的分享时,除了要设置密码保护文件内容外,还要注意设置打印限制,防止他人利用打印的方式,进行纸质文件的传播. 在使用pdfFactory安全策略时,我们可以通过设定禁止打印的方式,完全 ...
- word选择+快捷键
统一修改红色章节标题字体:将鼠标放置在章节标题中,前提是各章节标题采用的格式是一样的,单击"选择"-"选择格式相似的文本"即可全部选中进行设置 如下图,章节标题 ...
- sql常用函数整理
SQL中包含以下七种类型的函数: 聚合函数:返回汇总值. 转型函数:将一种数据类型转换为另外一种. 日期函数:处理日期和时间. 数学函数:执行算术运算. 字符串函数:对字符串.二进制数据或表达式执行操 ...
- java基础:CompletionStage接口
CompletionStage是Java8新增接口,用于异步执行中的阶段处理:先看接口 可以简单划分为三类: 1.在上一阶段执行结束之后,一阶段结果作为指定函数的参数执行函数产生新的结果,apply/ ...
- C++ cout格式化输出完全攻略
写算法题的时候突然发现自己忘记基本的C++:cout格式化输出了,赶紧拉出以前的C++学习笔记重新看一看. 部分内容来自教程:C语言中文网(一个很棒的网站) 有时希望按照一定的格式进行输出,如按十六进 ...