api java 帮助文档 java api doc

Java—使用ApiDoc接口文档

---

前言介绍：

之前写过 使用Swagger编写Api接口文档 ，介绍了Java怎么使用Swagger做项目的Api接口文档。也百度过现在生成Api接口文档的工具,看到的都是Swagger或者是apidoc。

---

项目为什么需要Api接口文档：

• 因为前后端分离，需要前后端共同定义接口规范，在项目开发中需要有一个统一的文件进行更好的沟通。
• 在项目开发结束之后，日常的项目维护和人员更替，都需要有文档来记录，方便后期人员查看并继续维护项目。

---

自动生成Api接口文档工具：

swagger

官网地址：https://swagger.io/

apidoc

github地址：https://github.com/apidoc/apidoc

---

安装apidoc操作：

我这边先是手动安装的，然后在idea里面的也下载的apidoc的插件，我觉得应该不会有冲突问题。操作步骤如下。

手动安装：安装apidoc需要的软件（命令如下）：

• 确认当前电脑安装了node.js。检测是否安装命令：

node -h

如果没有安装，点击node.js下载安装。

• 安装apidoc

npm install apidoc -g

• 测试apidoc是否安装成功

apidoc -h

---

idea插件安装：idea工具下载apidoc插件：

• 我的idea快捷键：Ctrl + Alt + s 点击Plugins 搜索 apidoc

• 在idea下载插件过程中有无法下载的情况，请看操作步骤：

Ctrl + Alt + s 
	选择appearance&Behavior –> System Settings –> updates
	去掉 Use secure connection 的勾选即可。

• 在idea中安装完apidoc插件以后，点击接口方法名按右键：

• 出现如下图片，就可以编辑Api接口文档了。

---

自动生成apidoc接口文档操作：

• 新建apidoc.json文件位置如图所示

• apidoc.json内容

{
  "name": "接口说明文档"",
  "version": "版本号",
  "description": "项目描述",
  "title": "浏览器标题",
  "url": "测试地址",
}

• 带header示例

{
  "name": "接口说明文档", 
  "version": "版本号",
  "description": "项目描述",
  "title": "浏览器标题",
  "url":"测试地址",
  
  "header": {
    "title": "标题",
    "filename": "内容文件"
  },
  "footer": {
    "title": "",
    "filename": ""
  }
}

• 生成文档：

apidoc和swagger不同的是，接口文档和代码是分开的，当我们开发完成时，只需要在接口方法上加上apidoc指定的注释，最后通过命令生成文档。

apidoc -i apiTestDemo/ -o apidocDemo/

-i 指定源文件的目录，也就是项目的根目录。
-o 指定输出文档的目录，生成文档的地址。

• 生成完的文档：

---