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 学习之 ...
随机推荐
- UNP——第二章,端口号,套接字对,TCP,UDP输出
1.端口号 端口号用于区分使用相同协议的进程. TCP69 与 UDP69 是不同的. 端口号范围 0 - 65535, 其中 0- 1023 是保留端口. 2.套接字对 TCP服务通过套接字对,唯一 ...
- Scrum转型(一) 为什么敏捷和Scrum
1.1 为什么敏捷 由于传统的瀑布模型管理方法无法满足现代某些软件产品开发过程的特点,我们需要使用敏捷的方法(例如,Scrum是一个让我们关注于在短时间里交付高质量商业价值的敏捷框架). 需求频繁变动 ...
- setPriority()优先级
1 . 优先级表示重要程度或者紧急程度.但是能不能抢到资源也是不一定.2 . 分配优先级:反映线程的重要或紧急程度线程的优先级用1-10 表示,1的优先级最低,10的优先级最高,默认值是5 packa ...
- mds的cpu占用问题分析以及解决办法
前言 mds是ceph里面处理文件接口的组件,一旦使用文件系统,不可避免的会出现一种场景就是目录很多,目录里面的文件很多,而mds是一个单进程的组件,现在虽然有了muti mds,但稳定的使用的大部分 ...
- My SQL的基本操作(总结)
My SQL的基本操作(总结) 因为本人目前是学生,前一段时间因为一些原因没有按时更新博客,今天我来总结一下My SQL的基本操作. 一.下载与安装 windows版本MySQL下载地址: http: ...
- tp5 日志的用途以及简单使用
相信大家对日志这个词都很熟悉,那么日志通常是用来做什么的呢? 找错误和监控 正常来说,日志对维运的帮助是最大的,特别是服务器或者是程序出现错误的时候. 那么现在我们就来看看,tp框架的日志是怎么设置的 ...
- guitar pro 系列教程(十八):Guitar Pro怎么设置吉他谱的局部速度?
关于Guitar Pro的使用功能我们在前面的文章也有讲了不少,对于新手的小伙伴,就小编个人而言,在吉他编曲,演绎方面遇到的困难不是一点两点,我们只有通过学习了解他的全部,才能在以后的吉他创作中得心印 ...
- django基本内容
1,流程 1.1 了解web程序工作流程 1.2 django生命周期 2,django介绍 目的:了解Django框架的作用和特点 作用: 简便.快速的开发数据库驱动的网站 django的优 ...
- jenkins、gitlab配置CI/CD
1. 在gitlab中创建好项目(gitlab的安装和基本使用这里不在说明) 2. 创建jenkins任务 jenkins 需要几个插件请先安装好 - Git plugin - GitLab Plug ...
- go创建动态库
*nix *nix创建so比较方便,写好go代码之后,直接一条命令搞定. go build -buildmode=c-shared -o libgobblob.so 命令执行之后,会生成libgobb ...