在SpringBoot项目中，我们经常用到JSON转换、发送HTTP请求这样的操作，所以我们要给Java项目导入一些常用的工具库。下面我要导入的是不需要做额外配置的工具库，咱们一起操作一下。

一、导入基础工具库

在pom.xml文件中添加上述各种依赖库。

<dependency>
	<groupId>cn.hutool</groupId>
	<artifactId>hutool-all</artifactId>
  <version>5.6.3</version>
</dependency>
<dependency>
	<groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpcore</artifactId>
  <version>4.4.13</version>
</dependency>
<dependency>
	<groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.5</version>
</dependency>
<dependency>
	<groupId>com.google.zxing</groupId>
	<artifactId>core</artifactId>
  <version>3.3.3</version>
</dependency>

二、定义R类

在前后端分离的架构中，后端返回给移动端或者前端的数据最好能有固定的格式，比如JSON中哪个属性是状态码，哪个属性是消息内容，哪个属性是业务数据等等。如果我们能定义一个Java类，里面设置好相应的变量。将来Web方法返回的数据封装在这个封装类，然后Spring框架把数据转换成JSON格式。那么客户端得到的响应内容格式非常的统一。

我在com.example.emos.api.common.util包里面创建R类，里面有相应的变量保存状态码和业务消息。

package com.example.emos.api.common.util;

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, "未知异常，请联系管理员");
    }
}

以后Controller中所有的Web方法返回的结果都是R对象了。

三、整合SpringDoc

有整合过Swagger经历的同学，应该深有体会，配置类的内容写起来乱七八糟的，特别是让Swagger兼容JWT的时候，需要我们配置一长串的链式调用，看着就头疼。下面的内容是配置Swagger的做法，大家可以参考，代码看着就让人头晕。

@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;
    }
}

1. 引入SpringDoc依赖库

这里我淘汰了Swagger，用上了SpringDoc组件。SpringDoc的功能跟Swagger几乎一模一样，但是配置起来非常简单，几个注解就能搞定。在pom.xml文件中添加SpringDoc的依赖库。

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

2. 修改配置文件

在application.yml文件中定义SpringDoc的配置信息

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

3. 编写配置类

SpringDoc的配置需要我们创建一个配置类，至于类的名字叫什么无所谓。例如我在com.example.emos.api.config包里面创建SpringDocConfig类。

package com.example.emos.api.config;

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 SpringDocConfig {

}

其中@SecurityScheme注解定义的是JWT部分，也就是说，一会儿我们在Swagger页面上可以看到Authorize按钮，我们可以设置HTTP请求头上传的JWT令牌。当然了，其中请求头的名字叫做token（本项目用Sa-Token权限与认证框架，该框架要求请求头用token保存令牌），如果你后端的JWT要求的请求头名字不叫做这个，你可以在上面的注解中修改name属性。

4. 测试SpringDoc

为了测试SpringDoc的效果，可以创建案例测试一下。我在com.example.emos.api.controller包中创建UserController类。

@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);
    }
}

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

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

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