神思者 ·在SpringBoot项目中，我们经常用到JSON转换、发送HTTP请求这样的操作，所以我们要给Java项目导入一些常用的工具库。下面我要导入的是不需要做额外配置的工具库，咱们一起操作一下。
| 序号 | 工具库 | 备注 |
|---|---|---|
| 1 | hutool | 通用工具库 |
| 2 | commons-io | 文件IO通用工具库 |
| 3 | zxing | 生成二维码图片 |
| 4 | httpcore | HTTP状态码 |
在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>代码块预览 复制
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
在前后端分离的架构中，后端返回给移动端或者前端的数据最好能有固定的格式，比如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, "未知异常，请联系管理员"); } }代码块预览 复制
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
以后Controller中所有的Web方法返回的结果都是R对象了。
有整合过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
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
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>代码块预览 复制
- 1
- 2
- 3
- 4
- 5
2. 修改配置文件
在application.yml文件中定义SpringDoc的配置信息
springdoc: api-docs: enabled: true path: /doc-api.html swagger-ui: path: /swagger-ui.html disable-swagger-default-url: on代码块预览 复制
- 1
- 2
- 3
- 4
- 5
- 6
- 7
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 { }代码块预览 复制
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
其中@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); } }代码块预览 复制
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
运行SpringBoot项目，然后访问项目的SpringDoc页面，网址为http://localhost:8080/项目名称/swagger-ui.html，然后浏览器就能看到下面的内容。
选中我们我测试执行的Web方法，执行在线的测试。因为该Web方法没有设置授权和登陆验证，所以不需要输入Token令牌，直接可以测试，结果如下：
可以看到Web方法成功运行了，这么看来利用SpringDoc来替代原始的Swagger，的确非常的简单。
2025 imooc.com All Rights Reserved |