注释即文档，SpringBoot无注解实现swagger文档

作者: 星星y | 来源:发表于2020-09-12 20:40 被阅读0次

注释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

注释即文档，SpringBoot无注解实现swagger文档

注释vs注解

实现方式

Swagger2Controller

DocumentationCache

@EnableEasySwagger

WebApplicationContext获取Controller信息

读取Controller源码中注释，方法信息

反射修改DocumentationCache

线程启动

json保存文档

项目地址

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

程序员