dockit

基于javadoc的Markdown文档生成工具。Markdown document generator base on javadoc.

License

License

Categories

Categories

Maven Build Tools
GroupId

GroupId

win.hupubao
ArtifactId

ArtifactId

dockit-maven-plugin
Last Version

Last Version

2.1.2.RELEASE
Release Date

Release Date

Type

Type

maven-plugin
Description

Description

dockit
基于javadoc的Markdown文档生成工具。Markdown document generator base on javadoc.
Project URL

Project URL

https://github.com/ysdxz207/dockit
Source Code Management

Source Code Management

https://github.com/ysdxz207/dockit

Download dockit-maven-plugin

How to add to project

<plugin>
    <groupId>win.hupubao</groupId>
    <artifactId>dockit-maven-plugin</artifactId>
    <version>2.1.2.RELEASE</version>
</plugin>

Dependencies

compile (9)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib jar 1.3.10
org.jetbrains.kotlin : kotlin-reflect jar 1.3.11
org.apache.maven : maven-plugin-api jar 3.5.0
org.apache.maven : maven-project jar 2.2.1
org.apache.maven.plugin-tools : maven-plugin-annotations jar 3.5
com.github.javaparser : javaparser-core jar 3.7.1
com.github.jsonzou : jmockdata jar 4.0.0
com.alibaba : fastjson jar 1.2.54
com.vladsch.flexmark : flexmark-all jar 0.35.0

test (1)

Group / Artifact Type Version
junit : junit jar 4.12

Project Modules

There are no modules declared in this project.

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>com.hupubao</groupId>
    <artifactId>dockit-maven-plugin</artifactId>
    <version>2.1.4.RELEASE</version>
    <configuration>
        <templateCharset>UTF-8</templateCharset>
        <singleOutDir>false</singleOutDir>
        <outDir>${project.build.directory}/dockit</outDir>
        <!-- 自动打开生成的文档目录,默认false -->
        <autoOpenOutDir>true</autoOpenOutDir>
        <!-- 这里可以选择自定义模版 -->
        <!--<template>${basedir}/src/main/resources/dockit/TEMPLATE.MD</template>-->
    </configuration>
    <!--
    <executions>
        <execution>
            <phase>package</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,否,分页大小
 * @arg obj, Object, 否, 参数
 * @arg obj.name, String, 否, 名称
 * @arg obj.createTime, String, 否, 创建事件
 * @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),是否必填,参数描述

历史更新

  • 2.1.4.RELEASE
  1. 增加了参数:autoOpenOutDir,当环境支持的时候,会自动打开生成的文档所在的目录。
  2. 增加了未配置@dockit时的日志输出。
  • 2.1.3.RELEASE
  1. 2019-08-29因更换域名,更换了插件的groupId从win.hupubao改为com.hupubao
  • 2.1.1.RELEASE
  1. 解决字段描述中出现英文逗号则会丢失逗号后部分内容问题
  • 2.1.0.RELEASE
  1. 请求参数也可以嵌套对象了

  2. 增加请求参数示例

Versions

Version
2.1.2.RELEASE
2.1.1.RELEASE
2.1.0.RELEASE
2.0.0.RELEASE
1.0.3
1.0.2
1.0.1
1.0.0