基于javadoc的Markdown文档生成工具

Dockit

Dockit 是一个通过javadoc生成markdown文档的生成工具。

• 不依赖于@RequestMapping注解，直接根据javadoc中是否有@title来生成接口文档

• 可应用于dubbo项目中

• 若需要dockit生成文档，则需要在类的javadoc中加入@dockit 如：

/**
 * @author ysdxz207
 * @date 2018-08-02
 * @dockit 阿福接口
 */

• 生成dockit目录结构如下：

dockit - 阿福接口 - 阿福列表接口.MD

• 若不需要按目录生成，则可以设置插件参数singleOutDir=true

1. pom.xml:

<plugin>
    <groupId>win.hupubao</groupId>
    <artifactId>dockit-maven-plugin</artifactId>
    <version>2.0.0.RELEASE</version>
    <configuration>
        <templateCharset>UTF-8</templateCharset>
        <singleOutDir>false</singleOutDir>
        <outDir>${project.build.directory}/dockit</outDir>
        <template>${basedir}/src/main/resources/dockit/TEMPLATE.MD</template>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>dockit</goal>
            </goals>
        </execution>
    </executions>
</plugin>

1. mvn clean dockit:dockit

2. 你也可以根据默认模版 DEFAULT.MD 自定义你的文档模版，将插件template参数修改为你的模板路径即可

3. javadoc 格式如下：

/**
 * @title 阿福列表接口
 * @desc 获取阿福列表
 * @url afu.list
 * @version 1.0.0
 * @status 可用
 * @method POST
 * @arg pageNum,Integer,是,页码
 * @arg pageSize,Integer,否,分页大小
 * @resArg service,Object,是,请求服务，原样返回
 * @resArg service.subObject,Object,是,service子对象
 * @resArg service.subObject.id,Integer,是,service子对象ID
 * @resArg service.subObject.name,String,是,service子对象名
 * @resArg service.subArray,Array,是,service子数组
 * @resArg service.subArray.name,String,是,service子数组名
 * @resArg list,Array,是,阿福列表
 * @resArg list.id,String,是,ID
 * @resArg list.name,String,是,名称
 * @resArg list.type,String,是,类型
 * @resArg list.createTime,String,是,创建时间
 * @resArg list.content,String,是,内容
 * @resArg list.arr,Array,是,数组
 * @resArg list.arr.arrName,String,是,数组名
 * @resArg list.arr.arrValue,String,是,数组值
 * @resArg list.arr.subArr,Array,是,子数组
 * @resArg list.arr.subArr.subArrId,String,是,子数组ID
 * @resArg list.arr.subArr.subArrName,String,是,子数组名
 * @resArg list.arr.subObj,Object,是,子对象
 * @resArg list.arr.subObj.objId,String,是,子对象ID
 * @resArg list.arr.subObj.objName,String,是,子对象名
 *
 */
 

• 生成样例

• 标签释义

标签名	释义	格式
@title	接口名，若需要此接口生成文档，则此标签必选	-
@arg	请求参数	参数名,类型,是否必填,参数描述
@resArg	返回参数	参数名[.属性],类型(除其他类型外还可以是Object或Array),是否必填,参数描述

仓库地址

https://github.com/ysdxz207/dockit

欢迎star

转载于:https://my.oschina.net/u/1394407/blog/3005488