JApiDocs —— 接口文档快速生成工具

古城微笑少年丶 2022-11-13 10:29 347阅读 0赞

# 是什么 #

## 背景 ##

> 在程序员的工作中, 代码编写虽然占了一很大部分, 但是编写接口文档也同样费时费力, 而我们常用的[swagger(丝袜哥)][swagger]已经能帮助我们自动生成接口文档, 但是缺点是不能够导出文档  
> 而 [showdoc + runapi][showdoc _ runapi] 能够帮助我们导出接口文档, 并实现接口文档管理交接, 模板编写, 接口调试等功能. 但是缺点也同样明显, 需要人为输入的内容较多**二者各有千秋, 可以根据具体业务酌情使用.  
> 而下面我们介绍的是一种新的接口文档生成和导出工具 ------ JApiDocs**

## 简介 ##

> **JApiDocs是一个无需额外注解、开箱即用的 SpringBoot 接口文档自动生成工具。**

**特点**

*  使用方便. 两步搞定
 *  支持文档导出. (Markdown)
 *  支持多模块项目
 *  支持自定义代码模板
 *  与其他接口文档插件无缝集成

# 怎么用 #

## 使用步骤 ##

1.  **添加依赖**
    
        <dependency>
          <groupId>io.github.yedaxia</groupId>
          <artifactId>japidocs</artifactId>
          <version>1.4.3</version>
        </dependency>
2.  **配置参数**  
    在启动类的main函数中添加以下代码, 并制定目录以及项目信息.  
    待启动项目后, 接口文档便生成到指定目录了
    
        DocsConfig config = new DocsConfig();
        config.setProjectPath("your springboot project path"); // 项目根目录
        config.setProjectName("ProjectName"); // 项目名称
        config.setApiVersion("V1.0");       // 声明该API的版本
        config.setDocsPath("your api docs path"); // 生成API 文档所在目录
        config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
        Docs.buildHtmlDocs(config); // 执行生成文档
    
    生成之后的接口文档目录结构  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70]
3.  **如果想要导出Markdown格式的接口文档, 只需在配置参数代码中添加一行**  
    如果想要pdf或者word格式文档, 可以通过 [typora][]把 markdown 格式导出成 pdf 或者 word 格式。
    
        config.addPlugin(new MarkdownDocPlugin());

## 使用注意 ##

> **文档内容的详细程度取决于你在书写类, 方法, 属性时是否进行正确的注释**  
> 例如下图其中的一个接口方法, 我们可以看到接口描述与我们在方法的注释是一致的

**接口方法注释**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 1]  
**对应接口文档的回显**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 2]

## 效果展示 ##

**接口文档主页展示 index.html**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 3]  
**接口内容格式展示**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 4]

**Markdown文档格式展示**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 5]

## 多模块项目配置 ##

如果源码路径没有全部识别出来，可以通过`config.addJavaSrcPath`来添加模块的源码路径，注意要添加到`src/main/java`这一级。

--------------------

更多JApiDocs详细配置请见 [ JApiDocs官网][JApiDocs]  
想要了解更多接口文档工具可见[ 推荐几个在线文档生成神器][Link 1]

[swagger]: https://timepause.blog.csdn.net/article/details/102544252
[showdoc _ runapi]: https://timepause.blog.csdn.net/article/details/109651352
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70]: /images/20221022/bc85ca574c094ab1b91e4d68481cdbf6.png
[typora]: https://www.typora.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 1]: /images/20221022/30a2b6260fac4b3f822206c163763168.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 2]: /images/20221022/b9188051921747bea0434d405c2bde28.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 3]: /images/20221022/5835b37dd6444dfaba7f3f7b8dfe7b0d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 4]: /images/20221022/786eda737672486993e8179db72f52b0.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20210326164807590.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMzcxNTU2,size_16,color_FFFFFF,t_70
[JApiDocs]: https://japidocs.agilestudio.cn/#/zh-cn/?id=%E5%85%A5%E9%97%A8
[Link 1]: https://mp.weixin.qq.com/s/C0HDnsX9tclRODkER2f6sA