SpringBoot实现Swagger接口响应信息自定义（一）

swagger提供了一套完整的接口文档解决方案，只需在pom文件中加入swagger相关的包并简单配置一下即可得到一份完整的接口文档，想要更详细规范的信息还可在Controller类中加入类似@ApiOperation注解，诸如这些swagger的基本使用网上有很多教程，这里不在赘述。
本篇主要讲述如何使用SpringBoot实现Swagger接口信息自定义。

场景

接口相关信息如路径、参数等数据可能来自枚举、模板文档、数据库等。

初版解决方案：依据swagger工作原理，实现ApiListingScannerPlugin接口

为了搞清楚各个参数的含义是什么，这里将关键的信息用1、2、3数字替代，对于其他的一些参数的含义，字面意思相信也能理解，实在不能理解可以自行阅读下源码

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import com.fasterxml.classmate.TypeResolver;
import com.google.common.collect.Sets;
import com.xxx.UserDTO;

import springfox.documentation.builders.OperationBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiDescription;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.ApiListingScannerPlugin;
import springfox.documentation.spi.service.contexts.DocumentationContext;
import springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator;

@Component
public class CustomSwaggerScanner implements ApiListingScannerPlugin {
    @Override
    public List<ApiDescription> apply(DocumentationContext context) {
    	// 可以从数据库、模板文档等读取数据，最终拼接为List<ApiDescription>形式，这里为了简便直接返回固定数据
        return new ArrayList<>(Arrays.asList(
                new ApiDescription("/api/test/user",
                        "1",
                        Arrays.asList(
                                new OperationBuilder(
                                        new CachingOperationNameGenerator())
                                        .method(HttpMethod.POST)
                                        .produces(Sets.newHashSet(MediaType.ALL_VALUE))
                                        .summary("2")
                                        .notes("3")
                                        .tags(Sets.newHashSet("4"))
                                        .parameters(Arrays.asList(
                                                new ParameterBuilder()
                                                        .type(new TypeResolver().resolve(UserDTO.class))
                                                        .name("5")
                                                        .description("6")
                                                        .parameterType("body")
                                                        .required(true)
                                                        .modelRef(new ModelRef("UserDTO"))
                                                        .build(),
                                                new ParameterBuilder()
                                                        .type(new TypeResolver().resolve(String.class))
                                                        .name("7")
                                                        .description("8")
                                                        .parameterType("query")
                                                        .required(false)
                                                        .modelRef(new ModelRef("string"))
                                                        .build()
                                        ))
                                        .build()),
                        false)));
    }

    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
}

效果如下：

存在的问题

由于SpringBoot容器启动便会扫描接口，该组件会被加载，并执行apply方法，显然只会加载一次，当新增或修改接口的时候必须重启容器才能够自动更新。
实际上，重启容器才能自动更新是不可接受的，因为这样和直接用swagger扫描我们写的Controller没什么两样，何必再自定义接口响应呢？所以下一篇SpringBoot实现Swagger接口响应信息自定义（二）将会讲到如何解决这个问题。