利用javadoc定制自己的接口文档（一）

前言

　　自己在公司实习的时候是负责后台开发，自己在编写完接口之后还需要对外提供接口文档，接口文档的形式也在自己手里经历了以下几个阶段的演化。
　　第一阶段：使用的是excel，通过excel的链接将接口和参数描述链接在一起，这样可维护性极差：（1）一个方法要加一个参数，或者减一个参数，那个excel的参数页就整体上移或者下移，于是，就要把所有方法的链接都改一遍。（2）前端开发一不小心就点到其他方法的参数描述中，开发时不是频繁交流，就是靠猜。成本极大
　　第二阶段：后来摒弃这种低级的excel形式，以html形式展示给前端，一个方法一个页面，再用一个页面A将所有方法的页面以超链接的形式整合起来，这样点击页面A的每个方法名称，就能跳转到对应的方法描述中。这样前端确实省心了不少，但是给后端带来很大的工作量：（1）我写一个接口，我就要写一个html，尤其是当参数很多时，我就要不断的复制粘贴，既繁琐又无聊。（2）一个标签写错，整个页面就错了，还要花费很多时间去debug，时间成本太大。
　　第三阶段：这样持续一段时间后，自己实在受不了，就想着能不能通过代码来自动生成这些文档。想起来java帮助文档的生成形式，然后再网上查阅了一些资料，知道了javadoclet，自己尝试着写了一个自定义的doclet——doclet1，利用这个自定义的doclet中生成接口文档。（自己还顺便帮Android端生成访问url的类，Android开发的人应该很烦按照接口文档中的入参生成对应的类，然后进行url访问吧，毕竟一不小粘错，又要debug好久）
　　第四阶段：在最开始的doclet1中，自己将所有内容都写在了里面，包含输出地址，html内容，等等。耦合性太强：当需要修改页面样式或者布局的时候，就需要修改doclet1代码。后来自己将html模板和java模板从中抽出，利用freemarker定制自己的模板，做了自己的第二代doclet——doclet2。
　　第五阶段：依照之前的思路，自己想如何将那些自定义标签，输入输出路径等也从中抽出来。这些内容以什么形式来展示，如何与doclet，freemarker整合，参考着HtmlDoclet源码来设计。
　　接下来的内容，我将依照自己从开始都现在自己所接触到的内容依次进行阐述，大致内容为：java Doclet概述，javadoc命令简单说明，freemark概述，第五阶段doclet设计思路

一、Doclet概述

　　Doclet 是用 JavaTM编程语言编写的程序，它用 doclet API 指定 Javadoc 工具的输出内容和格式。缺省情况下，由Standard类 来生成 HTML 形式的 API 文档（在Standard的start方法中调用了HtmlDoclet的start方法：return HtmlDoclet.start(var0)）。用户可以利用 doclet API从头开始编写 自定义的doclet，也可以对标准 doclet 进行修改，以适合自己的需要。
　　下面是创建和使用自己的 doclet 的基本步骤：
　　１.编写用来构成 doclet 的 Java 程序。为使用 doclet API，该程序应导入 com.sun.javadoc.*。程序的入口是一个带有 public static boolean start 方法的类，它将 RootDoc 作为参数。
　　２.编译 doclet。
　　３.用 -doclet 选项运行 javadoc 工具，生成 doclet 指定的输出。如果运行 javadoc 时未使用 -doclet 命令行选项，则按缺省状态的标准 doclet 生成 HTML 格式的 API 文档。
　　值得注意的是：doclet API 类文件在 JDK 软件的 lib/tools.jar 文件中，所以当编译 doclet 和使用自定义 doclet 时，tools.jar 必须在类路径上。为此，可以对 javac 和 javadoc 使用 -classpath 选项。
（包 com.sun.javadoc 由定义 doclet API 的接口组成。JDKTM 软件的 lib/tools.jar 文件包含这些接口及实现这些接口的类的私有包。tools.jar 文件还包括实现标准 doclet 的类。）

举个简单的doclet例子，让我们可以对doclet的运行方式有所了解：

inport com.sun.javadoc.*;

public class listClass{
    public static boolean start(RootDoc root){
        ClassDoc[] classes = root.classes();
        for(int i=0 ; i < classex.length ; i+=){
            System.out.println(classes[i]);
        }
        return true;
    }
}

　　该 doclet 将取出 Javadoc 所操作的一些类，然后将它们的名称输到标准输出上。
　　就该 doclet 而言，首先应注意到：
　　1.为使用 doclet API，程序导入了 com.sun.javadoc.*。
　　2.对于所有 doclets，入口点均为 public static boolean start 方法。
　　3.start 方法将 RootDoc 作为参数使用。该参数携带运行 javadoc 时命令行指定的所有选项信息，以及 Javadoc 所操作的类和包的信息。
　　接下来，编译listClass doclet，正如前面所说，编译时需要加上tools.jar的位置，对本例如下：

javac -classpath D:\ProgramFileZhaoShiqiang\java\jdk1.7\lib\tools.jar listClass.java

　　编译完成后，为了运行listClass doclet，必须用javadoc的doclet标记指向编译后的doclet，例如，要在testClass上运行doclet，需要使用命令：

javadoc -doclet listClass -classpath D:\ProgramFileZhaoShiqiang\java\jdk1.7\lib\tools.jar testClass.java

　　输出结果将是字符串 “testClass”。注意：该命令也要求类路径中包含 tools.jar。
　　关于命令行选项的说明，如果运行javadoc -help，就会看到javadoc工具有两个命令行选项集。一个选项集是普通选项集，它适用于任何 doclet。另一个则专门用于标准 doclet。下面我将其中部分重要的命令行选项进行说明
　　（javadoc可以自定义标签和自定义命令行选项，这里就不展开讨论了，如果大家有兴趣可以参考http://dadi520.iteye.com/blog/545897，作为简单介绍doclet，这篇博客很不错，上面大部分内容也是摘自这篇博客。只不过自己写的doclet从start之后就完全重新设计了）

二、javadoc命令行选项

　　在命令行中运行javadoc -help命令，将显示javadoc命令行语法，如下：
　　　javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
　　参数可以按照任意顺序排列，大多数参数都简单易懂，这节最后我会提几个参数的注意事项
　　Packagenames 包列表。这个选项可以是一系列的包名（用空格隔开），例如java.lang java.lang.reflect java.awt。不过，因为javadoc不递归作用于子包，不允许对包名使用通配符；所以你必须显示地列出希望建立文档的每一个包。
　　Sourcefiles 源文件列表。这个选项可以是一系列的源文件名（用空格隔开），可以使用通配符。javadoc允许四种源文件：类源代码文件、包描述文件、总体概述文件、其他杂文件。
　　@files 包含文件。为了简化javadoc命令，你可以把需要建立文档的文件名和包名放在一个或多个文本文件中。例如，为了简化下面命令：
javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3
你可以建立一个名称为mypackage.txt的文件，其内容如下：
　　com.mypackage1
　　com.mypackage2
　　com.mypackage3
然后执行下面命令即可：
　　javadoc -d apidoc @mypackage.txt
注：
　　1.-sourcepath sourcepathlist 指定包的源文件搜索路径。但是必须注意，只有在javadoc命令中指定了包名的时候才可以使用-sourcepath选项。如果指定了包名，而省略了- sourcepath，那么javadoc使用类路径查找源文件。
　　举例说明：假定你打算为com.mypackage建立文档，其源文件的位置是C: usersrc。那么你可以使用下面的命令：
　　　javadoc -sourcepath c:usersrc com.mypackage
　　2. -classpath classpathlist 指定javadoc查找”引用类”的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录。 Classpathlist可以包含多个路径（使用;隔开）。如果省略-classpath，则javadoc使用-sourcepath查找源文件和类 文件。
　　举例说明：假定你打算为com.mypackage建立文档，其源文件的位置是C:usersrc，包依赖C:userlib中的库。那么你可以使 用下面的命令：
javadoc -classpath c:userlib -sourcepath c:usersrc com.mypackage
（更多详细命令，可以参考博客http://blog.chinaunix.net/uid-725717-id-2060139.html）

3、自定义doclet

　　正如前面介绍的，自定义doclet，需要有public static boolean start(RootDoc root)是如果只有这个方法，那么我们只能使用javadoc规定的参数（即普通选项集中的参数），不能使用sun标准的doclet参数（即标准选项集中的参数），比较sun的HtmlDoclet源码，就会发现，只要增加下面2个方法就可以使用标准选项集中的参数：

public static int optionLength(String option) {  
        // Construct temporary configuration for check  
        return (ConfigurationImpl.getInstance()).optionLength(option);  
    }  

public static boolean validOptions(String options[][], DocErrorReporter reporter) {  
        // Construct temporary configuration for check  
        return (ConfigurationImpl.getInstance()).validOptions(options, reporter);  
    }  

　　看过第一节中提及的博客的人应该熟悉在两个函数，这两个函数就是为了扩展命令行选项的。

　　最后介绍一下自己自定义的标签：
　　类相关的注解有：
　　　　类的描述：description
　　　　类的访问路径：uri
　　　
　　方法相关的注解有
　　　　方法访问路径：uri
　　　　方法类别（读方法or写方法）：type
　　　　方法描述：description
　　　　UE中如何找到接口：path
　　　　支持格式（默认json）：datatype
　　　　请求方式（默认post）：
　　　　传入参数描述：param
　　　　注意事项（默认无）：notice
　　　　返回的json格式：returnjson
　　　　输出参数描述：returnparam

　　类相关的注解使用如下：

/**
 * @uri 2.0/dynamic
 * @description 动态类
 * @author zhaoshiqiang@jchvip.com
 */
@Controller
@RequestMapping("/2.0/dynamic")
public class DynamicController {
   
}

　　方法相关的注解使用如下：

/**
     * @uri publish
     * @description 发布动态
     * @type write
     * @path 发布动态
     * @param comment~true~string~动态内容
     * @param userid~true~string~用户id
     * @param imgs~false~list(array)~发动态上传的图片时，不同图片用逗号分隔