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

是什么

背景

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

简介

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

特点

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

怎么用

使用步骤

1. 添加依赖 <dependency> <groupId>io.github.yedaxiagroupId> <artifactId>japidocsartifactId> <version>1.4.3version> 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); // 执行生成文档 生成之后的接口文档目录结构

1. 如果想要导出Markdown格式的接口文档, 只需在配置参数代码中添加一行 如果想要pdf或者word格式文档, 可以通过 typora把 markdown 格式导出成 pdf 或者 word 格式。 config.addPlugin(new MarkdownDocPlugin());

使用注意

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

接口方法注释

对应接口文档的回显

效果展示

接口文档主页展示 index.html

接口内容格式展示

Markdown文档格式展示

多模块项目配置

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

​

​