apidoc使用教程

更多干货

React 入门实战（干货）
分布式实战（干货）
spring cloud 实战（干货）
mybatis 实战（干货）
spring boot 实战（干货）
构建中小型互联网企业架构（干货）

在开发后台接口的过程中，我们肯定要提供一份api接口文档给终端app。目前大多数的app的接口请求应该都是http+json的方式。但是一直苦于做不出份漂亮的api文档，用word写，也太丑了。。怎么才能做出一份像腾讯、新浪微博等各种开放api平台那样漂亮的api文档呢？apidoc。

官网地址：http://apidocjs.com

开放API已经成为当下主流平台的一个要素，特别对于社交、电商类的平台开放API更成为了竞争力的一种。开放API文档的完整性、可阅读性往往影响着接入方是否能顺利地、快速地接入到平台，一份好的、统一的API文档也是开放平台不可或缺的要素。

apidoc是通过源码中的注释来生成API文档，所以只要识别兼容现今大部分流行语言的注释方法便达到了兼容语言的效果。

有了它，我们只需要在写源码的时候顺手写上一些简单的注释，就可以生成出漂亮的文档了（当然，有同学会问文档不是先定义的吗？你把接口的源码声明好不就ok啦？写个简单的，然后用apidoc生成一下就出文档了)

它可以对API的各种版本等级进行对比。所以无论是前端开发人员还是你都可以追溯API版本的变化

1、使用步骤

安装nodejs。去http://www.nodejs.org/下载安装一个nodejs

安装apidoc：命令行输入：npm install apidoc -g 貌似是在线安装的，稍等一下即可。

准备一个目录myapp，下面放源码文件，源码文件中要按照apidoc的规范写好注释。具体规范参见官网，我这里就不翻译了。例如我写java的源码：

/**
 * 此接口不要去实现，仅作为输出api文档用的
 * @author xumin
 *
 */
@Deprecated
public interface ApiDoc {  /**
     *
     * @api {get} /company/list 获取公司信息
     * @apiName 获取公司列表
     * @apiGroup All
     * @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 分页数据对象数组
     * @apiSuccessExample Success-Response:
     *  HTTP/1.1 200 OK
     * {
     * code:0,
     * msg:'success',
     * data:{}
     *  }
     *
     *  @apiError All 对应<code>id</code>的用户没找到 asdfasdf
     *  @apiErrorExample {json} Error-Response:
     *  HTTP/1.1 404 Not Found
     *  {
     *   code:1,
     *   msg:'user not found',
     *   }
     *
     * @param param
     * @return
     * @throws Exception
     */  void a();
}

生成api文档

apidoc -i myapp/ -o apidoc/ -t mytemplate/

myapp是当前工作目录下的源码目录

apidoc是用于存放生成出的文档文件的目录

mytemplate是自定义模板文件夹，刚开始用，可以不指定，后面有需要了再研究怎么自定义模板吧

如果看到“success: Done.”说明生成成功，到 apidoc目录下打开index.html查看生成的文档.

apidoc使用教程-编写漂亮的api文档相关推荐

CMDB建设补充：教你用django+drf 怎么去生成漂亮的API文档
废话不多说,先看效果图安装插件 pip install drf_yasg 在settings.py的INSTALLED_APPS里添加drf_yasg 在urls.py里面添加下面代码 from r ...
什么是API？ [如何编写和阅读API文档]
随着API在互联网时代中变得越来越普遍,不仅是编程人员会用到,现在也会要求产品经理或互联网运营会调试和对接API.看这篇文章的你可能会使用或开发API,或者两者兼而有之. 因此,对你来说,不仅要了解如 ...
Node与apidoc的邂逅——NodeJS Restful 的API文档生成
作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...
Spring Boot 2.x基础教程：Swagger静态API文档的生成
点击蓝色"程序猿DD"关注我回复"资源"获取独家整理的学习资料! 作者 | 翟永超来源 | didispace.com/spring-boot-learni ...
如何编写优质的API文档
编写技术文档,是令众多开发者望而生畏的任务之一.它本身是一件费时费力才能做好的工作.可是大多数时候,人们却总是想抄抄捷径,这样做的结果往往非常令人遗憾的,因为优质的技术文档是决定你的项目是否引人关注的 ...
[aspnetcore.apidoc]一款很不错的api文档生成工具
简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api文档角度来说,从前后端文档沟通角度来 ...
java apidoc案例_java 自动生成api 文档：apidoc
官网:apidocjs 首先声明下,apidoc是基于注释来生成文档的,它不基于任何框架,而且支持大多数编程语言,适用于java项目.跟已有的项目框架没有任何关系一.apidoc简介 apidoc通 ...
Eolink 征文活动- -后端研发需要的API文档工具
Eolink功能太多,一两篇文章聊不完,这篇文章只是聊聊Eolink的API文档管理功能. 首先大致说说我所认知的API文档工具历史. 我所知的API文档工具历史我是2010年左右参 ...
API文档自动生成的方法
编写API文档是API编写人员的噩梦,而API文档通常是由API研发人员编写.由于API文档创建繁琐,需要记录的内容比较广,结束了API开发任务后,还要仔细编写API文档,给研发人员带来额外的工作量. ...

apidoc使用教程-编写漂亮的api文档

apidoc使用教程

更多干货

1、使用步骤

apidoc使用教程-编写漂亮的api文档相关推荐

最新文章

热门文章