利用javadoc注釋自動生成Swagger注解

更新時間：2023年08月13日 09:20:50 作者：三火哥

由于現(xiàn)在controller方法上面沒有swagger注解，只能拿到接口url地址，無法獲得接口功能描述，所以本文為大家介紹一下如何利用javadoc注釋自動生成Swagger注解，感興趣的可以了解下

目的

可視化接口管理平臺，通過接口管理平臺一目了然知道接口的作用，接口上面擴(kuò)展了哪些功能，從而做到對應(yīng)用程序代碼零侵入

現(xiàn)狀

由于現(xiàn)在controller方法上面沒有swagger注解，只能拿到接口url地址，無法獲得接口功能描述。

值得慶幸的是我們的代碼非常規(guī)范每個方法都有標(biāo)準(zhǔn)的javadoc注釋，于是就想到了獲取javadoc注釋的描述自動生成swagger注解

思路

1，AOP切面，你會發(fā)現(xiàn)根本無法獲取javadoc，這個方案就直接pass掉了

2，讀文件流獲取文件內(nèi)容解析出想要的數(shù)據(jù)，雖然可以但是費(fèi)時費(fèi)力，不是最優(yōu)的方案

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(), "項(xiàng)目路徑不存在");
        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(), "項(xiàng)目路徑不存在");
        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;
    }
}

效果

/**
 * 數(shù)據(jù)庫管理
 *
 * @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();
    }
}

/**
 * 數(shù)據(jù)庫管理
 *
 * @author xiongyan
 * @date 2023/03/13
 */
@RestController
@RequestMapping("/web/database")
@Api(value = "數(shù)據(jù)庫管理")
public class WebDatabaseController {
    /**
     * 分頁列表
     *
     * @param request
     * @return
     */
    @PostMapping("/page")
    @ApiOperation(value = "數(shù)據(jù)庫管理-分頁列表")
    public ScmResponse<ScmPage<DatabaseDto>> page(@RequestBody DatabaseRequest request) {
        return ScmResponseUtil.success();
    }
}

可以看到通過javadoc自動生成了swagger注解，尤其是對于我們這樣微服務(wù)拆分很細(xì)的，應(yīng)用非常多，接口更是多的，通過這種方式效率最高的