通过javadoc注释自动生成Swagger注解
站长
· 阅读数 9
目的
可视化接口管理平台，通过接口管理平台一目了然知道接口的作用，接口上面扩展了哪些功能，从而做到对应用程序代码零侵入
现状
由于现在controller方法上面没有swagger注解，只能拿到接口url地址，无法获得接口功能描述。
值得庆幸的是我们的代码非常规范每个方法都有标准的javadoc注释，于是就想到了获取javadoc注释的描述自动生成swagger注解
思路
1，AOP切面，你会发现根本无法获取javadoc，这个方案就直接pass掉了
2，读文件流获取文件内容解析出想要的数据，虽然可以但是费时费力，不是最优的方案
3，使用开源的javaparser难道不香吗，非常香就它了
javaparser
<dependency>
<groupId>com.github.javaparser</groupId>
<artifactId>javaparser-core</artifactId>
<version>3.25.4</version>
</dependency>
import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.util.HashMap;
import java.util.Map;
import com.fuchuang.scm.common.util.ScmAssert;
import com.github.javaparser.StaticJavaParser;
import com.github.javaparser.ast.CompilationUnit;
import com.github.javaparser.ast.body.ClassOrInterfaceDeclaration;
import com.github.javaparser.ast.body.MethodDeclaration;
import cn.hutool.core.util.StrUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
/**
* 通过javadoc注释自动生成Swagger注解
*
* @author xiongyan
* @date 2023/7/7
*/
public class Sw {
public static void main(String[] args) throws Exception {
String clientPath = "/Users/xiongyan/Documents/work/fc-cdc/fc-cdc-api/src/main/java/com/fc/cdc/controller";
String controllerPath = "/Users/xiongyan/Documents/work/fc-cdc/fc-cdc-api/src/main/java/com/fc/cdc/controller";
Map<String, ClassOrInterfaceDeclaration> clientMap = Sw.clientMap(clientPath);
File project = new File(controllerPath);
ScmAssert.isTrue(project.exists(), "项目路径不存在");
for (File file : project.listFiles()) {
CompilationUnit cu = StaticJavaParser.parse(file);
ClassOrInterfaceDeclaration classDeclaration = cu.findFirst(ClassOrInterfaceDeclaration.class).orElse(null);
if (null == classDeclaration) {
continue;
}
String classComment = null;
Map<String, String> methodCommentMap = new HashMap<>();
if (classDeclaration.getImplementedTypes().size() > 0) {
String interfaceName = classDeclaration.getImplementedTypes(0).getNameAsString();
ClassOrInterfaceDeclaration interfaceDeclaration = clientMap.get(interfaceName);
if (null == interfaceDeclaration) {
continue;
}
if (interfaceDeclaration.getJavadoc().isPresent()) {
classComment = interfaceDeclaration.getJavadoc().get().getDescription().toText();
}
for (MethodDeclaration method : interfaceDeclaration.getMethods()) {
if (!method.getJavadoc().isPresent()) {
continue;
}
methodCommentMap.put(method.getNameAsString(), method.getJavadoc().get().getDescription().toText());
}
}
if (StrUtil.isEmpty(classComment)) {
if (classDeclaration.getJavadoc().isPresent()) {
classComment = classDeclaration.getJavadoc().get().getDescription().toText();
} else {
classComment = classDeclaration.getNameAsString();
}
}
if (!classDeclaration.getAnnotationByClass(Api.class).isPresent()) {
classDeclaration.addAndGetAnnotation(Api.class).addPair("value", "\"" + classComment + "\"");
}
for (MethodDeclaration method : classDeclaration.getMethods()) {
if (method.getAnnotationByClass(ApiOperation.class).isPresent()) {
continue;
}
String methodComment = methodCommentMap.get(method.getNameAsString());
if (StrUtil.isEmpty(methodComment)) {
if (method.getJavadoc().isPresent()) {
methodComment = method.getJavadoc().get().getDescription().toText();
} else {
methodComment = method.getNameAsString();
}
}
method.addAndGetAnnotation(ApiOperation.class).addPair("value", "\"" + classComment + "-" + methodComment + "\"");
}
FileOutputStream outputStream = new FileOutputStream(file);
outputStream.write(cu.toString().getBytes());
}
}
private static Map<String, ClassOrInterfaceDeclaration> clientMap(String path) throws FileNotFoundException {
File project = new File(path);
ScmAssert.isTrue(project.exists(), "项目路径不存在");
Map<String, ClassOrInterfaceDeclaration> clientMap = new HashMap<>();
for (File file : project.listFiles()) {
CompilationUnit cu = StaticJavaParser.parse(file);
if (null == cu) {
continue;
}
ClassOrInterfaceDeclaration classDeclaration = cu.findFirst(ClassOrInterfaceDeclaration.class).orElse(null);
if (null != classDeclaration && classDeclaration.isInterface()) {
clientMap.put(classDeclaration.getNameAsString(), classDeclaration);
}
}
return clientMap;
}
}
效果
/**
* 数据库管理
*
* @author xiongyan
* @date 2023/03/13
*/
@RestController
@RequestMapping("/web/database")
public class WebDatabaseController {
/**
* 分页列表
*
* @param request
* @return
*/
@PostMapping("/page")
public ScmResponse<ScmPage<DatabaseDto>> page(@RequestBody DatabaseRequest request) {
return ScmResponseUtil.success();
}
}
/**
* 数据库管理
*
* @author xiongyan
* @date 2023/03/13
*/
@RestController
@RequestMapping("/web/database")
@Api(value = "数据库管理")
public class WebDatabaseController {
/**
* 分页列表
*
* @param request
* @return
*/
@PostMapping("/page")
@ApiOperation(value = "数据库管理-分页列表")
public ScmResponse<ScmPage<DatabaseDto>> page(@RequestBody DatabaseRequest request) {
return ScmResponseUtil.success();
}
}
可以看到通过javadoc自动生成了swagger注解，尤其是对于我们这样微服务拆分很细的，应用非常多，接口更是多的，通过这种方式效率最高的
接口文档
服务器启动就可以把 接口应用名称，接口URL地址，接口请求方式，接口描述，接口请求结构，接口响应结构 数据收集进行注册自动生成接口文档
接口扩展
1，数据脱敏
2，操作日志
3，防重复提交
4，接口幂等
5，接口限流
6，黑白名单
7，权限控制
8，。。。。。