注释vs注解
在进行接口开发时，我们通常会使用swagger生成接口文档。为了让使用者能更好的使用文档，就要使用注解标记每个接口的名称，参数说明。比如以下代码：
@Api(tags = "学生接口")
@RestController
@RequestMapping("web/v1/student")
public class StudentController {
@ApiOperation("根据编号获取学生信息")
@ApiImplicitParams(
@ApiImplicitParam(name = "stu_no", value = "学生编号"))
@GetMapping("getByNo")
public StudentVO getByNO(@RequestParam("stu_no") String stuNo) {
StudentVO stu = new StudentVO();
stu.setStuNo(stuNo);
stu.setName("张三");
return stu;
}
@ApiOperation("添加学生信息")
@ApiImplicitParams(
{
@ApiImplicitParam(name = "name", value = "学生名称", defaultValue = "张三"),
@ApiImplicitParam(name = "no", value = "学生编号", defaultValue = "std-10001", required = true)
}
)
@PostMapping("add")
public StudentVO addStudent(String name, String no) {
StudentVO s = new StudentVO();
s.setName(name);
s.setStuNo(no);
return s;
}
}
在实际开发中，需要用各种注解表示接口功能。尤其是接口参数，我们需要用@ApiImplicitParam依次标记每个参数，这种工作往往单调重复，而且还会使我们的业务代码更加复杂。
那我们能不能使用更简单的方式定义文档呢？在平常开发中，我们会对我们的一些代码添加上注释来说明某些功能。通过/** */可以注释一个Class类，或者一个方法,同时在注释中使用@param来说明某个参数的具体含义。这种方式看起来更加简洁明了，比如如下Controller类：
/**
* 学生接口
*/
@RestController
@RequestMapping("web/v1/student")
public class StudentController {
/**
* 根据编号获取学生信息
* @param stuNo 学生编号
*/
@GetMapping("getByNo")
public StudentVO getByNO(@RequestParam("stu_no") String stuNo) {
StudentVO stu = new StudentVO();
stu.setStuNo(stuNo);
stu.setName("张三");
return stu;
}
/**
* 添加学生信息
* @param name 学生名称|张三
* @param no 学生编号|required|std-10001
*/
@PostMapping("add")
public StudentVO addStudent(String name, String no) {
StudentVO s = new StudentVO();
s.setName(name);
s.setStuNo(no);
return s;
}
}
不需要用更多的注解，只需给我们的类和方法加上注释就能生成文档岂不是更香么。
实现方式
Swagger2Controller
我们通过http://localhost:8080/swagger-ui.html查看接口文档时，可以查看到下面的api-docs的ajax请求，里面包含了所有的接口信息。
swagger-ui
它对应的
Controller为Swagger2Controller
Swagger2Controller
DocumentationCache
通过debug调试获取请求api-docs接口时的相关信息可以找到关键的DocumentationCache类，里面存储了文档的所有信息。最终swagger文档信息是通过它生成的。
DocumentationCache
所以我们只需修改DocumentationCache就能修改swagger的文档信息。通过源码可以发现DocumentationCache对象是通过依赖注入赋值的。所以我们也可以通过@Autowired等注解获取它。
@EnableEasySwagger
为了能够配置方便，我们使用一个@EnableEasySwagger注解开启注释生成文档功能。
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@Import({EasySwaggerConfig.class})
@Documented
public @interface EnableEasySwagger {
}
我们使用EasySwaggerConfigIOC注入保存DocumentationCache实例，同时还需要WebApplicationContext这个类来获取所有的Controller信息。
@Configuration
public class EasySwaggerConfig {
@Autowired
DocumentationCache documentationCache;
@Autowired
WebApplicationContext applicationContext;
public EasySwaggerConfig() {
}
@Bean
Swagger2Hook provideInit() {
return new Swagger2Hook(documentationCache, applicationContext);
}
}
核心逻辑在Swagger2Hook中。
WebApplicationContext获取Controller信息
我们需要通过WebApplicationContext获取所有的Controller信息，如类名，请求接口地址等。然后更加类名扫描工程源码目录。因为注释信息是无法编译到class文件的，所以就需要读取工程目录中的源码文件，依次遍历每个Controller中的注释信息。
/**
* 获取所有url
*/
private void scanAllUrl() {
RequestMappingHandlerMapping mapping = applicationContext.getBean(RequestMappingHandlerMapping.class);
// 获取url与类和方法的对应信息
Map<RequestMappingInfo, HandlerMethod> map = mapping.getHandlerMethods();
for (RequestMappingInfo req : map.keySet()) {
HandlerMethod hm = map.get(req);
String url = req.getPatternsCondition().getPatterns().iterator().next();
String className = hm.getBeanType().getName();
ApiDoc apiDoc = new ApiDoc();
apiDoc.controllerClass = className;
controllerClasses.add(className);
apiDoc.methodName = hm.getMethod().getName();
docInfo.apiMap.put(url, apiDoc);
}
if (hasSrc) scanControllerDoc();
}
读取Controller源码中注释，方法信息
/**
* 扫描controller文档
*/
private void scanControllerDoc() {
for (String cls : controllerClasses) {
File sourceFile = getSourceFile(projectDir, cls);
if (sourceFile != null) {
parseControllerDoc(sourceFile, cls);
}
}
}
private static final String DOC_START = "^\\s*(/\\*\\*)$";
private static final String DOC_END = "^\\s*\\*/$";
private static final String DOC_CLASS = "^.* *class .+$";
private static final String DOC_METHOD_KT = "^\\s*fun (\\S*)\\(.*$";
private static final String DOC_METHOD_JAVA = "^\\s*public \\S+ (\\S*)\\(.*$";
private static final String DOC_PARAMS = "^\\s*\\* @param\\s+(.*)$";
private static final String DOC_FIELD_JAVA = "^\\s*(public|private) \\S+ (\\S+);\\s*//(\\S+)$";
private static final String DOC_FIELD_KT = "^\\s*(var|val) (\\S+):.*//(\\S+)$";
private void parseControllerDoc(File sourceFile, String controllerClass) {
BufferedReader reader = null;
boolean isJava = sourceFile.getName().endsWith(".java");
try {
reader = new BufferedReader(new FileReader(sourceFile));
String line;
String docDescription = "";
Map<String, String> params = new HashMap<>();
String controllerDescription = "";
while ((line = reader.readLine()) != null) {
if (line.matches(DOC_START)) {
docIndex = 0;
params = new HashMap<>();
hasDoc = true;
}
if (line.matches(DOC_END)) {
docIndex = -2;
}
if (docIndex == 1) {
docDescription = trimDocDescription(line);
}
if (line.matches(DOC_CLASS)) {
docIndex = -1;
if (hasDoc) {
controllerDescription = docDescription;
hasDoc = false;
}
}
if (line.matches(DOC_PARAMS)) {
String namedParam = getRexValue(DOC_PARAMS, line);
if (namedParam != null) {
String[] array = namedParam.split("\\s+");
if (array.length >= 2) {
params.put(array[0], substringArray(1, array));
}
}
}
scanControllerMethodDoc(
isJava,
controllerClass,
controllerDescription,
line, docDescription, params
);
if (docIndex != -2) docIndex++;
}
} catch (FileNotFoundException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally {
if (reader != null) {
try {
reader.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
/**
* 扫描方法注释
*/
private void scanControllerMethodDoc(boolean isJava, String controllerName, String controllerDescription,
String line, String docDescription, Map<String, String> params) {
String regex = isJava ? DOC_METHOD_JAVA : DOC_METHOD_KT;
if (line.matches(regex)) {
String methodName = getRexValue(regex, line);
methodName = fixMethodName(methodName);
ApiDoc apiDoc = getApiDocBy(controllerName, methodName);
if (apiDoc != null) {
if (hasDoc) {
apiDoc.description = docDescription;
Utils.processRequestParam(params, controllerName, methodName);
apiDoc.params = params;
}
apiDoc.controllerDescription = controllerDescription;
}
if (hasDoc) hasDoc = false;
}
}
反射修改DocumentationCache
在我们扫描所有Controller源码，获取到注释信息后，就可以修改DocumentationCache了，不过要注意到是，DocumentationCache中的相关属性是private final类型的，我们无法直接修改，需要通过反射的形式修改。
private void hookSwaggerDoc(Documentation doc) {
Multimap<String, ApiListing> apiList = doc.getApiListings();
for (ApiListing apiListing : apiList.values()) {
for (Model model : apiListing.getModels().values()) {
scanModelAndReplace(model);
}
for (ApiDescription apiDescription : apiListing.getApis()) {
String path = apiDescription.getPath();
ApiDoc apiDoc = docInfo.apiMap.get(path);
if (apiDoc != null) {
replaceParameter(apiDescription, apiDoc);
setOperationTags(apiDescription, apiDoc.controllerDescription);
setTags(apiListing.getTags(), apiDoc.controllerDescription, apiDoc.controllerClass);
}
}
}
}
线程启动
要注意的是，DocumentationCache最开始是没有相关文档信息的，我们在Spring Boot项目启动后再进行hook文档操作。这里我们可以通过多线程方式来完成。
public Swagger2Hook(DocumentationCache documentationCache, WebApplicationContext applicationContext) {
this.documentationCache = documentationCache;
this.applicationContext = applicationContext;
System.out.println("=======init easy swagger======");
new Thread() {
@Override
public void run() {
while (true) {
if (documentationCache.all().size() > 0) {
Swagger2Hook.this.run();
break;
}
try {
Thread.sleep(2000);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
}.start();
}
json保存文档
因为我们是扫描源文件获取文档信息的，在部署时无法获取。因此要将开发环境下的源码信息保存到resources目录下的json文件中，然后通过读取json文件而非扫描源码形式来修改swagger文档信息。
项目地址
https://github.com/iamyours/EasySwagger
https://search.maven.org/artifact/io.github.iamyours/easyswagger
