如何在SpringBoot中快速整合Swagger？

一、传统的Swagger配置方式

开发前后端分离或者微服务项目，调试后端Web接口必然会用到Swagger，特别是给Swagger添加上JWT的时候，配置代码写起来较为复杂和啰嗦。例如下面的这个配置类，就是给SpringBoot设置Swagger，并且附带上JWT，一堆集合，看着就让人头晕。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfoBuilder builder = new ApiInfoBuilder();
        builder.title("EMOS在线办公系统");
        ApiInfo info = builder.build();
        docket.apiInfo(info);

        ApiSelectorBuilder selectorBuilder = docket.select();
        selectorBuilder.paths(PathSelectors.any());
        selectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class));
        docket = selectorBuilder.build();

        ApiKey apiKey = new ApiKey("token", "token", "header");
        List<ApiKey> apiKeyList = new ArrayList<>();
        apiKeyList.add(apiKey);
        docket.securitySchemes(apiKeyList);

        AuthorizationScope scope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] scopes = {scope};
        SecurityReference reference = new SecurityReference("token", scopes);
        List refList = new ArrayList();
        refList.add(reference);
        SecurityContext context = SecurityContext.builder().securityReferences(refList).build();
        List cxtList = new ArrayList();
        cxtList.add(context);
        docket.securityContexts(cxtList);

        return docket;
    }
}

二、简化的配置方式

现在SpringDoc整合了Swagger，并且提供了非常简洁的整合方式，创建一个配置类，定义几个注解，Swagger就配置好了，非常的简单。

首先我们要在pom.xml文件中添加SpringDoc的依赖库，如下：

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-spring-boot-2-webmvc</artifactId>
    <version>3.1.5</version>
</dependency>

然后在SpringBoot的yml文件中，简单定义SpringDoc的基本设置

springdoc:
  api-docs:
    enabled: true
    path: /doc-api.html
  swagger-ui:
    path: /swagger-ui.html
    disable-swagger-default-url: on

然后创建一个配置类，内容可以这样写：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;


@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "emos-api",
                description = "Emos管理系统的后端Java项目",
                version = "1.0"
        )
)
@SecurityScheme(
        name = "Token",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer"
)
public class SwaggerConfig {

}

其中@SecurityScheme注解定义的是JWT部分，也就是说，一会儿我们在Swagger页面上可以看到Authorize按钮，我们可以设置HTTP请求头上传的JWT令牌。当然了，其中请求头的名字叫做Token，如果你后端的JWT要求的请求头名字不叫做这个，你可以在上面的注解中修改name属性。

三、写个测试程序

我们随便定义一个Controller，然后声明Web方法，一会我们通过SpringDoc在线测试一下Web方法。例如Web方法接收的数据需要做后端验证，那么我们先要导入后端验证的依赖库，先写一下pom.xml文件。

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-validation</artifactId>
</dependency>

接收Web请求提交的数据，我们要创建一个Form类，Form类的另一个好处是可以写注解做后端验证。

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;

@Data
@Schema(description = "检验登陆验证码")
public class CheckCodeForm {
    @NotBlank(message = "code不能为空")
    @Schema(description = "code")
    private String code;
}

下面编写一个Controller类，然后创建Web方法

@RestController
@RequestMapping("/user")
@Tag(description = "用户Web接口")
public class UserController {

    @PostMapping("/checCode")
    @Operation(summary = "检测登陆验证码")
    public R checCode(@Valid @RequestBody CheckCodeForm form) {
        return R.ok().put("result", true);
    }
}

上面的R类只是个封装响应数据的类而已，先导入依赖库，然后编写代码：

<dependency>
	<groupId>org.apache.httpcomponents</groupId>
	<artifactId>httpcore</artifactId>
	<version>4.4.13</version>
</dependency>

import org.apache.http.HttpStatus;

import java.util.HashMap;
import java.util.Map;

public class R extends HashMap<String, Object> {
    public R() {
        put("code", HttpStatus.SC_OK);
        put("msg", "success");
    }

    public R put(String key, Object value) {
        super.put(key, value);
        return this;
    }

    public static R ok() {
        return new R();
    }

    public static R ok(String msg) {
        R r = new R();
        r.put("msg", msg);
        return r;
    }

    public static R ok(Map<String, Object> map) {
        R r = new R();
        r.putAll(map);
        return r;
    }

    public static R error(int code, String msg) {
        R r = new R();
        r.put("code", code);
        r.put("msg", msg);
        return r;
    }

    public static R error(String msg) {
        return error(HttpStatus.SC_INTERNAL_SERVER_ERROR, msg);
    }

    public static R error() {
        return error(HttpStatus.SC_INTERNAL_SERVER_ERROR, "未知异常，请联系管理员");
    }
}

运行SpringBoot项目，然后访问项目的SpringDoc页面，网址为http://localhost:8080/项目名称/swagger-ui.html，然后浏览器就能看到下面的内容

选中我们我测试执行的Web方法，执行在线的测试。因为该Web方法没有设置授权和登陆验证，所以不需要输入Token令牌，直接可以测试，结果如下

可以看到Web方法成功运行了，这么看来利用SpringDoc来替代原始的Swagger，的确非常的简单。