• 写文档是件大事情，怎么弄好它？

    这里的文档指 API 接口文档。

    写接口文档，首先原始的方式是手写，即文档脱离源码，使用 Word 或者 Markdown 写好发布给前端人员。好处是适合前期接口评审，缺点也是明显，源码和文档不同步，两边改。

    Swagger 这样结合源码与文档的工具给我们带来了福音。Swagger 思路和问题我整理如下：

    • 文档内容写在 Swagger 自定义的注解上，这样通过导出得到一份 json 文件然后渲染 HTML 文档；
    • 注意是 Java **注解（Annotation）**而不是普通 Java 注释。同时本身就有 Java 方法的参数——如果你要既要写 Java 注释又要写 Swagger 注解，是不是重复？
    • 其实很多时候这类信息是一致的（当然不排除接口的入参和 Java 参数是两回事的情况），完全可以“合并同类项”
    • 于是有了另外一种思路：基于 Java 普通注释去导出文档，注解为辅，减少重复工作。这种思路很好，大家就这么干，很愉快地决定了
    • 另外补句，有人说 Swagger 入侵性太强。我觉得这个不好说，想零入侵是不可能滴……看着办吧。

    好~既然方向定了，就看看如何去实现吧，首当其冲的，怎么把 Java Comment 提炼出来？一开始我想到自然是正则表达式，话说俺最早搞 yui-ext（ExtJS 前身）文档就是用正则的，那时哪有什么 js 的文档工具，yui-ext 作者 Jack 也是自己写的文档工具。

    写了一个晚上的正则，虽然感觉自己的正则功力宝刀未老，还略有进步，但最终结论这——还是个——坑~果断放弃吧

    后来想起 JavaDoc 不就干这个的么？于是搜索一下，竟发现有 Doclet 这好东西，提供 API 调用 JavaDoc，十分强大。

    要认识 Doclet，网上文档就不少，我推荐下面几个：

    其他同类产品

    基于注释的典型就是 smart-doc。世界很大，其他同类可参考这文章：《求你别再用swagger了，给你推荐几个在线文档生成神器》。还是 superJavaDoc 也不错 https://github.com/chenhaoxiang/super-java-doc。

    为啥不用现有的呢？开始我也不知道，就一股脑地自己写轮子了……其实没想象中那么复杂，且听我娓娓道来……

    使用 Doclet

    其实 javadoc 在 jdk 目录下只是一个可执行程序，但是这个可执行程序是基于 jdk 的 tools.jar 的一个封装，也就是说 javadoc 实现在 tools.jar 中。

    具体怎么使用 Doclet 就不赘述了。使用方法参考我给的源码也是答案。

    使用 Doclet 过程中发现几个问题：

    • Java Bean 的注释写在字段 field 上，field 又是 private 的，例如下面代码：
    class A {
    /**
     * 是否 xx
     */
	private Boolean b;
}

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6

    读取 private 问题不大：classDoc.fields(false) 搞定，问题是 bean 有继承关系的，Doclet 就无能为力了。对此，我们通过反射也可以轻松搞定。

    • 方法注释的，不能读取来自 interface 定义的注释。直接解析某个类上面的注释自然没问题，但是它继承于其他接口呢？这是正常操作呀？如下：
    interface IController {
   /**
   * 设置状态
   */
	Boolean setStatus();
}

class Controller implements IController {
 // 这里就不写注释文档了
}

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

    Docket 同样无能为力。对此，笔者想到的办法是返回获取该类的所有接口，看哪个是有指定注解的，比如 @getCommentHere，表示从这里获取注释内容。前面说道，JavaDoc 为主，注解为辅，不是说完全排斥注解，注解还是挺好用的。当然我也知道自定义注解入侵性太强，所以还是优先使用 JavaDoc，以及它本来提供的标识。

    • 解析内部类。内部类（Inner Class）又叫内嵌类（Nested Class），ClassName 标识可以是 com.abc.service$Pojo 这样的，我喜欢把代码行数比较少的 Bean 作为内部类放在一个外部类中——可 Doclet 并不会因你传 $Pojo 而识别出来是内部类，咋搞？——我也头痛了很久，好在传入内部类外层的外部类，Doclet 是能够解析里面所有的内部类的，这样就行，我们解析好了，先存到一个 Map 之中，肯定包含你目标的那个内部类，返回即可。至于已经解析过了的，对 Map 判断下，找到返回就行。所以一开始识别了是内部类，其实接下来是对其外部类进行 Doclet 的解析。

    实现

    解析一个 Java 类，提取其字段注释和方法注释，当然也包括其类的信息，是为下列 Doclet Helper 也，循例也这里贴一下。

    package com.ajaxjs.fast_doc;

import java.util.AbstractCollection;
import java.util.AbstractList;
import java.util.ArrayList;
import java.util.List;

import org.springframework.util.CollectionUtils;
import org.springframework.util.ObjectUtils;

import com.ajaxjs.framework.PageResult;
import com.ajaxjs.util.ReflectUtil;
import com.ajaxjs.util.logger.LogHelper;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Type;
import com.sun.tools.javadoc.Main;

public class Doclet implements Model {
	private static final LogHelper LOGGER = LogHelper.getLog(Doclet.class);

	/**
	 * Docket 程序入口
	 * 
	 * @param params
	 * @param clz
	 * @return
	 */
	public static BeanInfo parseFieldsOfOneBean(Params params, Class<?> clz) {
		init(params, clz);
		BeanInfo bean = parseFieldsOfOneBean(clz); // 带注释的
		bean.values.addAll(getSuperFields(clz, params));// 附加父类的 fields

		return bean;
	}

	/**
	 * 解析某个 bean 的所有 fields(不包括父类的)
	 * 
	 * @param clz
	 * 
	 * @return
	 */
	private static BeanInfo parseFieldsOfOneBean(Class<?> clz) {
		BeanInfo beanInfo = new BeanInfo();
		beanInfo.name = clz.getSimpleName();
		beanInfo.type = clz.getName();
		beanInfo.values = new ArrayList<>();

		ClassDoc[] classes = root.classes();

		if (classes.length == 1) {
			ClassDoc classDoc = classes[0];
			beanInfo.description = classDoc.commentText();
			beanInfo.values = Util.makeListByArray(classDoc.fields(false), fieldDoc -> {
				Value v = new Value();
				v.name = fieldDoc.name();
				v.type = fieldDoc.type().simpleTypeName();
				v.description = fieldDoc.commentText();

				return v;
			});

			Class<?>[] interfaces = clz.getInterfaces();
			for (Class<?> _interface : interfaces) {

				LOGGER.info(_interface);
			}

			MethodDoc[] methods = classDoc.methods();
			for (MethodDoc methodDoc : methods) {
				LOGGER.info(methodDoc.commentText());

			}
		} else if (classes.length > 1) { // maybe inner clz
			for (ClassDoc clzDoc : classes) {
				/*
				 * qualifiedTypeName() 返回如 xxx.DetectDto.ResourcePlanResult 按照 clz$innerClz 风格转换
				 * xxx.DetectDto$ResourcePlanResult
				 */
				String fullType = clzDoc.qualifiedTypeName();
				String clzName = clzDoc.simpleTypeName();
				fullType = fullType.replace("." + clzName, "$" + clzName);
//				LOGGER.info(fullType);

				if (beanInfo != null && fullType.equals(beanInfo.type)) {
					if (BeanParser.CACHE.containsKey(fullType)) {
						continue; // 已经有
					} else {
						BeanInfo b = new BeanInfo();
						b.name = clzName;
						b.description = clzDoc.commentText();
						b.type = fullType;

						List<Value> simpleValues = new ArrayList<>();
						List<BeanInfo> beans = new ArrayList<>();

						Util.makeListByArray(clzDoc.fields(false), fieldDoc -> {
							Type type = fieldDoc.type();

							Value v = new Value();
							v.name = fieldDoc.name();
							v.type = type.simpleTypeName();
							v.description = fieldDoc.commentText();

							simpleValues.add(v);
							// TODO 递归 内嵌对象。没有 List 真实 Class 引用
//							if (ifSimpleValue(type))
//								simpleValues.add(v);
//							else {
//								BeanInfo bi = new BeanInfo();
//								bi.name = v.type;
//								bi.type = type.toString();
//								bi.description = v.description;
//								LOGGER.info(b.name + ">>>>>>>>>" + v.type);
//								
//								Class clz = ReflectUtil.getClassByName(bi.type);
//
//								if (!"Object".equals(v.type)) // Object 字段无法解析
//									parseFieldsOfOneBean(tempParams, clz, bi);
//
//								beans.add(bi);
//							}

							return v;
						});

						b.values = simpleValues;

						if (!CollectionUtils.isEmpty(beans))
							b.beans = beans;

						BeanParser.CACHE.put(fullType, b);
					}
				}
			}

			BeanInfo beanInCache = BeanParser.CACHE.get(beanInfo.type); // 还是要返回期待的那个

			if (beanInCache != null) {
				beanInfo.description = beanInCache.description;
				beanInfo.values = beanInCache.values;
				beanInfo.beans = beanInCache.beans;
			}
		} else
			LOGGER.warning("Doclet 没解析任何类");

		return beanInfo;
	}

	private final static String[] types = { "int", "java.lang.String", "java.lang.Integer", "java.lang.Boolean", "java.lang.Long" };

	/**
	 * 
	 * @param type
	 * @return
	 */
	public static boolean ifSimpleValue(Type type) {
		String t = type.toString();
//		LOGGER.info(t);
		for (String _t : types) {
			if (_t.equals(t))
				return true;
		}

		return false;
	}

	/**
	 * Doclet 不能获取父类成员
	 * 
	 * @param clazz
	 * @param params
	 * @return 只返回所有父类的 fields
	 */
	private static List<Value> getSuperFields(Class<?> clazz, Params params) {
		Class<?>[] allSuperClazz = ReflectUtil.getAllSuperClazz(clazz);
		List<Value> list = new ArrayList<>();

		if (!ObjectUtils.isEmpty(allSuperClazz)) {
			for (Class<?> clz : allSuperClazz) {
				if (clz == PageResult.class || clz == List.class || clz == ArrayList.class || clz == AbstractList.class || clz == AbstractCollection.class)
					continue;

				Params p = new Params();
				p.root = params.root;
				p.classPath = params.classPath;
				p.sourcePath = params.sourcePath;
				init(p, clz);
				BeanInfo superBeanInfo = parseFieldsOfOneBean(clz);// 父类的信息

				if (!CollectionUtils.isEmpty(superBeanInfo.values))
					list.addAll(superBeanInfo.values);
			}
		}

		return list;
	}

	private static void init(Params params, Class<?> clz) {
		params.sources = new ArrayList<>();

		String clzName = clz.getName();
		boolean isInnerClz = clzName.contains("$");

		if (isInnerClz) {
			clzName = clzName.replaceAll("\\$\\w+$", "");

			params.sources.add(params.root + Util.className2JavaFileName(clzName));
		} else
			params.sources.add(params.root + Util.className2JavaFileName(clz));

		init(params);
	}

	/**
	 * 初始化 Doclet 参数，包括 classpath 和 sourcepath -classpath 参数指定 源码文件及依赖库的 class
	 * 位置，不提供也可以执行，但无法获取到完整的注释信息(比如 annotation)
	 * 
	 * @param params Doclet 参数
	 */
	private static void init(Params params) {
		LOGGER.info("初始化 Doclet");
		init(params.sources, params.sourcePath, params.classPath);
	}

	private static void init(List<String> sources, String sourcePath, String classPath) {
		List<String> params = new ArrayList<>();
		params.add("-doclet");
		params.add(Doclet.class.getName());
		params.add("-docletpath");

		params.add(Doclet.class.getResource("/").getPath());
		params.add("-encoding");
		params.add("utf-8");

		if (sourcePath != null) {
			params.add("-sourcepath");
			params.add(sourcePath);
		}

		if (classPath != null) {
			params.add("-classpath");
			params.add(classPath);
		}

		params.addAll(sources);

		Main.execute(params.toArray(new String[params.size()]));
	}

	/** 文档根节点 */
	private static RootDoc root;

	/**
	 * javadoc 调用入口
	 * 
	 * @param root
	 * @return
	 */
	public static boolean start(RootDoc root) {
		Doclet.root = root;

		return true;
	}
}

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    • 42
    • 43
    • 44
    • 45
    • 46
    • 47
    • 48
    • 49
    • 50
    • 51
    • 52
    • 53
    • 54
    • 55
    • 56
    • 57
    • 58
    • 59
    • 60
    • 61
    • 62
    • 63
    • 64
    • 65
    • 66
    • 67
    • 68
    • 69
    • 70
    • 71
    • 72
    • 73
    • 74
    • 75
    • 76
    • 77
    • 78
    • 79
    • 80
    • 81
    • 82
    • 83
    • 84
    • 85
    • 86
    • 87
    • 88
    • 89
    • 90
    • 91
    • 92
    • 93
    • 94
    • 95
    • 96
    • 97
    • 98
    • 99
    • 100
    • 101
    • 102
    • 103
    • 104
    • 105
    • 106
    • 107
    • 108
    • 109
    • 110
    • 111
    • 112
    • 113
    • 114
    • 115
    • 116
    • 117
    • 118
    • 119
    • 120
    • 121
    • 122
    • 123
    • 124
    • 125
    • 126
    • 127
    • 128
    • 129
    • 130
    • 131
    • 132
    • 133
    • 134
    • 135
    • 136
    • 137
    • 138
    • 139
    • 140
    • 141
    • 142
    • 143
    • 144
    • 145
    • 146
    • 147
    • 148
    • 149
    • 150
    • 151
    • 152
    • 153
    • 154
    • 155
    • 156
    • 157
    • 158
    • 159
    • 160
    • 161
    • 162
    • 163
    • 164
    • 165
    • 166
    • 167
    • 168
    • 169
    • 170
    • 171
    • 172
    • 173
    • 174
    • 175
    • 176
    • 177
    • 178
    • 179
    • 180
    • 181
    • 182
    • 183
    • 184
    • 185
    • 186
    • 187
    • 188
    • 189
    • 190
    • 191
    • 192
    • 193
    • 194
    • 195
    • 196
    • 197
    • 198
    • 199
    • 200
    • 201
    • 202
    • 203
    • 204
    • 205
    • 206
    • 207
    • 208
    • 209
    • 210
    • 211
    • 212
    • 213
    • 214
    • 215
    • 216
    • 217
    • 218
    • 219
    • 220
    • 221
    • 222
    • 223
    • 224
    • 225
    • 226
    • 227
    • 228
    • 229
    • 230
    • 231
    • 232
    • 233
    • 234
    • 235
    • 236
    • 237
    • 238
    • 239
    • 240
    • 241
    • 242
    • 243
    • 244
    • 245
    • 246
    • 247
    • 248
    • 249
    • 250
    • 251
    • 252
    • 253
    • 254
    • 255
    • 256
    • 257
    • 258
    • 259
    • 260
    • 261
    • 262
    • 263
    • 264
    • 265
    • 266
    • 267

    当前只实现了字段的解析，方法的解析还要进一步实现，我会不断更新在源码库上：https://gitee.com/sp42_admin/ajaxjs/tree/master/aj-framework/src/main/java/com/ajaxjs/fast_doc。这工具名字姑且就叫 FastDoc，简单易记：）

  • 相关阅读:
    基于SSM的网络安全宣传网站设计与实现
    Go 通道机制与应用详解
    QUIC简介
    引领未来：AI Native与物联网(IoT)的革命性融合
    ssm基于javaweb体育运动会竞赛成绩管理系统springboot
    NTMFS4C05NT1G N-CH 30V 11.9A MOS管,PDF
    OpenVINS与MSCKF_VIO RK4积分对比
    气液分离器的选型介绍
    后端返回二进制文件，js 下载为xls或xlsx文件
    麒麟-v10系统添加字体方法
  • 原文地址：https://blog.csdn.net/zhangxin09/article/details/127632794