接口文档生成利器 JDoc
JDoc是基于JAVA开发的,针对主流web框架做的接口文档生成利器,只需极简配置就可以实现文档的生成,且对项目零入侵,主要目的是解决协作开发中接口文档及时更新,开发JDoc的想法来源于项目XDoc,项目地址https://git.oschina.net/treeleaf/xDoc 一直想开发一个文档生成器,没有找到合适的解决方法,项目中用到的javadoc给我了很大的帮助,在此感谢XDoc作者-风里的叶子
JDoc有如下主要特点
1.简单易用,配置极简
2.对项目零入侵,在不改变项目本身代码结构上加上JDoc的格式注解就可以快速生成文档,只对Controller层解析
JDoc使用
maven包依赖,javadoc.jar在工程lib目录下
<dependency>
<groupId>com.nmtx</groupId>
<artifactId>jdoc</artifactId>
<version>1.0</version>
</dependency>
<dependency>
<groupId>sun</groupId>
<artifactId>javadoc</artifactId>
<version>1.0</version>
</dependency>
JDoc配置文件,参考配置如下,配置文件放在resource文件夹中,名字为jdoc.properties
#指定java文件路径
java.source=src/test/java
#指定需要生成文档的包路径
package.name=com.nmtx.test
#指定采用的框架类型,目前支持jfinal,springmvc两种框架
parser.name=jfinal
#指定文档输出路径
out.path=test.html
#指定模版生成器,目前仅支持html
parser.formater=html
Jdoc注解格式如下 类注释
/**
* 我是测试controller
*
* @author lianghao
*
* 2017年3月23日
*/
我是测试为一级文档标题
方法注释
/**
* 我是测试接口
*
* @param username|用户名|Integer|必填
* @title 测试接口
* @respParam username|用户名|Integer|必填
* @respBody {username:23234}
*/
@param为请参数 可设置多个 参数名 描述 请求类型 是否必填
@title 接口标题
@respParam返回参数 参数名 描述 请求类型 是否必填 可设置多个
@respBody返回demo
JFinal框架中使用,因JFinal本身架构的原因,外部无法拿到对应根映射,JDoc提供两种方法解决
1.第一种配置,清除后缀方法,比如说TestController,认为访问的链接为/test
/**
* 配置访问路由
*/
@Override
public void configRoute(Routes me) {
//TODO 配置路由
new JFinalApiDocConfig().setClearSuffix("Controller").start();
}
2.第二种配置,与路由配置一致,调用add方法把路由加进去
new JFinalApiDocConfig().setUseClearSuffix(false).add("/jfinal", JFinalController.class).start();
SpringMVC,SpringBoot框架中使用如下
package com.nmtx.springmvc.doc.config;
import com.nmtx.doc.core.api.springmvc.SpringMVCApiDocConfig;
public class SpringDocBuilder {
public static void main(String[] args) {
SpringMVCApiDocConfig doc = new SpringMVCApiDocConfig();
doc.setConfigFilePath("jdoc.properties");
doc.start();
}
}
JDoc 工程地址 https://git.oschina.net/lianghao2016/JDoc
SpringMVC demo地址 https://git.oschina.net/lianghao2016/springmvc-jdoc-demo
JFinal demo地址 https://git.oschina.net/lianghao2016/jdoc-jfinal-demo
生成的api文档截图