加入 JFinal 开发者计划，使用 JBolt 极速开发平台做项目，效率大大提升，感受复杂代码也能写的那么易读、极简、优雅。
想在代码里写 javadoc 同时完成 api 文档，免得单独维护 api 文档。实在不忍心将 swagger 引入项目中，严重"污染"代码，破坏现有代码易读性的极简优雅。
找了一圈，smart-doc 是比较理想的，但是无奈不支持 JBolt。发现 JApiDocs 也是通过 javadoc 就能生成 api 文档，而且支持 JFinal，高高兴兴的去集成了。过程发遇到一些问题，总结一下分享出来。
首先，在 pom.xml 中引入 JApiDocs 的 maven 坐标。
<dependency> <groupId>io.github.yedaxia</groupId> <artifactId>japidocs</artifactId> <version>1.4.4</version> </dependency>
然后，需要写一个 api 文档生成类。注释中已经说明遇到问题了，请仔细核对。
/**
* JApiDocs 无需额外注解的 API 文档生成工具
* <p>
* 源码 https://github.com/YeDaxia/JApiDocs
* 文档 https://japidocs.agilestudio.cn/#/zh-cn/
*/
public class JApiDocsGenerator {
/**
* JApiDocs 生成器
*
* 如果报错，做如下检查：
* 1 javadoc @param 后是否有注释
* 2 src.main.java 目录中非 .java 扩展名文件内容要 // 注释起来
* 3 删除 config.setDocsPath 目录中的文件，再生成试试
* <p>
* 如果生成的 api 文档不是预期的，作如下检查：
* 1 必须在 configRoute(Routes me) 中已该方式 me.add("/xx/yy", xx.class, "/"); 定义 Controller
* 2 在需要生成 api 的 Controller 中添加 @ApiDoc 注解
* 3 如果要忽略某 action，在 action 上添加 @Ignore */
public static void main(String[] args) {
DocsConfig config = new DocsConfig();
config.setProjectPath("f:/zxd_workspace/used_car/src"); // root project path
config.setProjectName("used_car"); // project name
config.setApiVersion("v1.0"); // api version
// 这是项目下的目录，生成完之后。前端人员可以直接访问，查看接口文档进行接口对接
config.setDocsPath("f:/zxd_workspace/used_car/src/main/webapp/assets/apidocs"); // api docs target path
//config.addPlugin(new MarkdownDocPlugin());
config.setAutoGenerate(Boolean.FALSE); // auto generate
//config.setMvcFramework("JFinal");
Docs.buildHtmlDocs(config); // execute to generate
}
}举例，JFinal 主配置文件。
public class MainConfig extends JFinalConfig {
public void configRoute(Routes me) {
me.add("/wxa/car", CarApiController.class, "/");
}
}举例，具体的接口类，只需要在类上添加一个注解 @ApiDoc 即可。其他正常写 javadoc 的注释。
@ApiDoc
public class CarApiController extends JBoltApiBaseController {
@Inject
private BrandsService brandsService;
@Inject
private SeriesService seriesService;
/**
* 获取所有车辆品牌列表
*/
public void getBrandsAll() {
renderJBoltApiSuccessWithData(brandsService.getBrandsAll());
}
/**
* 获取车系列表
*
* @param brand 品牌中文名称
*/
public void getSeries(String brand) {
renderJBoltApiSuccessWithData(seriesService.getSeriesByBrand(brand));
}生成完的样子，看看效果。抛开样式颜值这一块，前端需要的接口信息都有了，很清爽。
如果接口过多，不方便找，左上角能通过接口中文名搜索。
我将生成完的 html 文档输出到项目目录中，方便前端人员直接访问查看文档，需要不检测/assets/apidocs/目录的静态资源，配置如下。
public void configHandler(Handlers me) {
JBoltBaseHandler baseHandler = new JBoltBaseHandler();
//配置baseHandler 处理页面basePath pmkey 静态资源html直接访问拦截等
baseHandler.unlimited("/assets/plugins/", "/admin/druid/monitor/", "/neditor/", "/assets/apidocs/");
me.add(baseHandler);
}整体来说，基本满足免维护接口文档的需求，且基本不用写多余的注解，平时只需要将 javadoc 写好即可。
如果想让文档生成的更完善，比如接口的是 get 还是 post，需要在 action 上添加 @ApiDoc(method = "get")。我觉得写着麻烦，和前端人员约定好接口规范，获取用 get，提交用 post，就够用了。
关于导出格式
能导出 html 、markdown 格式，不支持 postman。但是，提供了插件 IPluginSupport，可以自己写插件导出 postman 格式或任意格式。之后我会写一个导出 postman 格式的插件分享出来。
-------
没想到这么受欢迎，JApiDocs 导出 postman 格式插件已经分享了（传送门）。
