apidoc使用记录

在后端开发过程中,接口文档的书写也是十分重要的,使用office软件自己编写出来的文档比较耗时,可以使用apidoc来在线生成接口文档。

一、下载安装nodejs,可以去官网下载https://nodejs.org/en/,安装过程直接点击下一步到完成即可。

二、到你的开发项目根目录下新建模板json,主要标识一些公共参数:apidoc.json,内容如下:

{
  "name": "接口文档",
  "version": "1.0.0",
  "description": "小王的接口文档",
  "title": "小王的接口文档",
  "url" : "http://localhost:8070",
  "sampleUrl":"http://localhost:8070"
}

三、使用注释的方式声明需要生成接口文档的数据,例如:

/**
     * @api {post} /code/index 测试接口
     * @apiName 测试接口
     * @apiGroup 测试
     * @apiVersion 0.1.0
     * @apiDescription 这是一个测试接口
     * @apiParam {int} pageNum分页大小
     * @apiSuccess {String} code 结果码
     * @apiSuccess {String} msg 消息说明
     * @apiSuccess {Object} data 分页数据封装
     * @apiSuccess {int} data.count 总记录数
     * @apiSuccess {Object[]} data.list 分页数据对象数组
     * @apiSuccess {String} data.list.name 姓名
     * @apiSuccess {String} data.list.sex 性别
     */
    @RequestMapping("/index")
    @ResponseBody
    public Object index(Integer pageNum) {
       // do something ......
    }

需要注意的是@apiGroup默认是不兼容中文的,需要修改一下api_group.js文件里的代码,我的nodejs安装完之后是在C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers这个目录。找到这一行group = group.replace(/[^\w]/g, ‘_‘);注释即可。

四、加上注释之后,cmd到项目根目录,运行apidoc可生成在线接口文档,可以跟参数-o 指定生成目录,然后将该目录nginx配置一下,你的小伙伴就可以在线访问了:)

效果如下:

五、必要的情况下注释参数(如@apiName等)的释义可以进一步查询学习。

原文地址:https://www.cnblogs.com/mark8080/p/10366603.html

时间: 02-12

apidoc使用记录的相关文章

如何利用apidoc来写接口文档

在开发后台接口的过程中,肯定要提供一份api接口文档给终端.一直用word写,太丑了..怎么才能做出一份漂亮的api文档呢?找了好久发现了今天的主角-apidoc. 官网地址:http://apidocjs.com 开放API已经成为当下主流平台的一个要素,特别对于社交.电商类的平台开放API更成为了竞争力的一种.开放API文档的完整性.可阅读性往往影响着接入方是否能顺利地.快速地接入到平台,一份好的.统一的API文档也是开放平台不可或缺的要素. apidoc是通过源码中的注释来生成API文档,

apidoc,一个相当不错的文档生成器

http://apidocjs.com/ 例子:myapp目录下的MyCode.java /** * * @api {get} /company/list 获取公司信息 * @apiName 获取公司列表 * @apiGroup All * @apiVersion 0.1.0 * @apiDescription 接口详细描述 * * @apiParam {int} pageNum分页大小 * * @apiSuccess {String} code 结果码 * @apiSuccess {Strin

老男孩Linux运维第41期20170917开班第四周学习重点课堂记录

第1章 必知必会文件 配置文件位置 该文件作用 /etc/sysconfig/network-scripts/ifcfg-eth0 第一块网卡的配置文件 同setup中的network /etc/resolv.conf 客户端DNS配置文件,优先级低于网卡配置文件 /etc/hosts 主要作用是定义IP地址和主机名的映射关系(域名解析),是一个映射IP地址和主机名的规定 /etc/sysconfig/network 用于配置hostname和networking /etc/fstab 开机自动

SSISDB8:查看SSISDB记录Package执行的消息

在执行Package时,SSISDB都会创建唯一的OperationID 和 ExecutionID,标识对package执行的操作和执行实例(Execution Instance),并记录operation message,统计executable的执行时间,便于developers 优化package的设计,对package进行故障排除. 一,在package发生错误时,查看失败的Executable An executable is a task or container that you

使用插件bootstrap-table实现表格记录的查询、分页、排序等处理

在业务系统开发中,对表格记录的查询.分页.排序等处理是非常常见的,在Web开发中,可以采用很多功能强大的插件来满足要求,且能极大的提高开发效率,本随笔介绍这个bootstrap-table是一款非常有名的开源表格插件,在很多项目中广泛的应用.Bootstrap-table插件提供了非常丰富的属性设置,可以实现查询.分页.排序.复选框.设置显示列.Card view视图.主从表显示.合并列.国际化处理等处理功能,而且该插件同时也提供了一些不错的扩展功能,如移动行.移动列位置等一些特殊的功能,插件可

Git 使用记录

在win7平台已经安装好了git的情况下: 1,Git 本地仓库建立与使用步骤: (2)新建立文件夹: $ mkdir learngit $ cd learngit $ pwd /Users/michael/learngit (1)引入git: 通过git init命令把这个目录变成Git可以管理的仓库: $ git init Initialized empty Git repository in /Users/michael/learngit/.git/ (3)添加文件:git add fil

前端学HTTP之日志记录

前面的话 几乎所有的服务器和代理都会记录下它们所处理的HTTP事务摘要.这么做出于一系列的原因:跟踪使用情况.安全性.计费.错误检测等等.本文将谥介绍日志记录 记录内容 大多数情况下,日志的记录出于两种原因:査找服务器或代理中存在的问题(比如,哪些请求失败了),或者是生成Web站点访问方式的统计信息.统计数据对市场营销.计费和容量规划(比如,决定是否需要增加服务器或带宽)都非常有用 可以把一个HTTP事务中所有的首部都记录下来,但对每天要处理数百万个事务的服务器和代理来说,这些数据的体积超大,很

ClientDataSet中动态添加计算字段并用计算字段显示记录的UpdateStatus

ClientDataSet中每条记录都有UpdateStatus=(usUnmodified, usModified, usInserted, usDeleted)记录该条数据是修改的,删除的,还是新增的等.有时候我们只想看修改的或新增的或删除的就可能用到这一属性.下图用计算字段显示UpdateStatus状态. ********************************************************************************************

MySQL删除重复记录的方法

参考网上的方法,总结了产出重复记录的方法,欢迎交流. 方法1:创建一个新表临时储存数据 假设我们有一个存在多个字段的表,表中有部分数据的若干字段重复,此时我们可以使用DISTINCT这个关键字对表数据进行筛选. 1 CREATE [TEMPORARY] TABLE temp LIKE origin_tb; 2 INSERT temp(attr1,attr2,...) SELECT DISTINCT attr1,attr2,... FROM origin_tb; 3 DELETE FROM ori

北塔网管软件BTSO2.5安装过程记录

北塔网管软件据说是同类比较好的,原来的BTIM系列好像停止更新了,用BTSO版本代替,叫智慧运维平台,据说有各种改进,先把安装过程记录下来,以备以后重装. BTSO分两个部分:平台服务器和注册服务器,可以安装到一台主机,也可以分开,他们要能够通讯,否则认为盗版,注册要记录系统环境.要识别原版光盘,反正国产的软件版权意识近乎变态. 说明上要求win2008r2ent中文版或者win2012企业中文版,先试了2012,注册菜单不出现,重新用2008安装.顺序如下: 1.安装BETA-BTSO_2.5