开发前后端分离或者微服务项目，调试后端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 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的依赖库，如下：
org.springdoc
springdoc-openapi-spring-boot-2-webmvc
3.1.5
然后在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文件。
org.springframework.boot
spring-boot-starter-validation
接收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类只是个封装响应数据的类而已，先导入依赖库，然后编写代码：
org.apache.httpcomponents
httpcore
4.4.13
import org.apache.http.HttpStatus;
import java.util.HashMap;
import java.util.Map;
public class R extends HashMap {
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 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，的确非常的简单。
