apidoc 安装、生成文档和部署到远程服务器,外网访问接口文档

最新推荐文章于 2024-05-15 12:37:51 发布

无、涯

最新推荐文章于 2024-05-15 12:37:51 发布

阅读量3.2k

点赞数

分类专栏： apidoc 文章标签： apidoc 安装生成接口文档部署服务器

本文链接：https://blog.csdn.net/a704397849/article/details/100560342

版权

apidoc 专栏收录该内容

4 篇文章

订阅专栏

node.js 安装

apidoc 是用 node.js实现的，所以若没有安装node.js，需要先安装node.js

官网：https://nodejs.org/en/点击打开链接；
windows64位下载地址https://nodejs.org/dist/v8.9.4/node-v8.9.4-x64.msi下载,下载好后双击安装即可。

apidoc安装

win + R 输入cmd 打开命令行窗口
在这里插入图片描述

apidoc官网安装介绍：http://apidocjs.com/#install

cmd命令行窗口输入 npm install apidoc -g

npm install apidoc -g

测试是否安装成功,cmd命令行窗口输入 apidoc -h

apidoc -h

整合到项目中

在项目根目录新建一个 apidoc.json 文件，简单配置编辑内容如下：
apidoc.json

{
  "name": "APIDOC接口文档",
  "version": "1.0.0",
  "description": "开发文档",
  "title": "开发接口文档",
  "url" : "http://localhost:8080"
}

更多的配置项请参考apidoc官方配置介绍 http://apidocjs.com/#configuration

注：如果没有任何配置文件也是没问题的，照样能够用命令apidoc 打包生成项目接口文档，只不过会报警告 {“message”:“Please create an apidoc.json configuration file.”,“level”:“warn”}，生成的文档一些地方用默认值如标题，描述等

apidoc接口注释的使用

apidoc接口注释官网介绍

常用注解就那几个，也很简单，看下官网的就行了

一个粟子

    /**
    * @api {POST} /user/account/change/password 修改密码
    * @apiDescription 修改密码
    * @apiGroup  AccountController
    * @apiParam {String} phone 手机号
    * @apiParam {String} verify 验证码
    * @apiParam {String} newPwd 新密码
    *
    * @apiParamExample {json} 请求示例:
    * {
    *
    * }
    * @apiSuccessExample {json} 成功响应:
    * HTTP/1.1 200 OK
    * {
    *   "code":"0",
    *   "desc":"success",
    *   "data":{
    *
    *   }
    * }
    * @apiVersion 1.0.0
    */
    @PostMapping("/user/account/change/password")
    public String changePassword(@RequestBody String paramsJson, HttpServletRequest request) {
    	//......
    }

idea 中快速写apidoc的接口注释(用apidoc.json也能配置类似的功能),可以使用idea提供的自定义模板，可以看下：
idea java修改类方法注释模块，快速生成apidoc常用注释接口文档模板
 idea java代码注释中@标签模板创建，apidoc接口文档@标签模板创建

生成apidoc文档

接口注释写完后，我们就可以用apidoc命令打包生成接口文档了。很简单，就下面一个命令

apidoc -i ./ -o doc

参数介绍:

i 是输入源, -i ./ 表示要生成apidoc接口文档的项目目录就是当前目录
o 是输出，-o doc 表示当前目录下doc 是接口文档的输出目录
输入输出目录根据自己需求更改。

win + R 输入cmd 按回车, 打开cmd命令行窗口输入 apidoc -i src -o dest
src是要打包生成接口文档项目的根目录， dest 是接口文档生成到哪里

我是用idea开发,idea 自带cmd命令行窗口，并且已经是在项目当前家目录，我直接执行apidoc -i ./ -o doc
会将当前项目的接口文档打包生成到项目家目录下的 doc ，如下：
在这里插入图片描述

本地生成了api文档，本地可以查看，将生成的doc目录下index.html 用浏览器打开，如下：
在这里插入图片描述
这是在本地给自己看，那要给前端开发人员看咋办，下面介绍apidoc接口文档部署到远端服务器上。

将本地生成的apidoc文档上传到nginx反向代理静态资源目录

不知道上传资源到服务器？看这里
如果远端服务器没安装 nginx,那么看下这篇 centos7服务器安装运行nginx,配置静态资源反向代理
我的nignx 静态资源反向代理的家目录是 /opt/www_80/ ,端口是默认的80
将本地打包好的 apidoc 目录 doc 整个都上传到服务器 /opt/www_80/ 目录下

然后就能够通过浏览器外网访问放在服务器上的apidoc接口文档了，浏览器输入
外网ip地址/doc/index.html ,如下:
在这里插入图片描述