我是靠谱客的博主 怕孤独高山,这篇文章主要介绍SpringBoot集成SwaggerSpringBoot集成Swagger,现在分享给大家,希望可以做个参考。

SpringBoot集成Swagger

Swagger-UI

简介

Swagger-UI是HTML, Javascript, CSS的一个集合,可以动态地根据注解生成在线API文档。

常用注解

  • @Api:用于修饰Controller类,生成Controller相关文档信息
  • @ApiOperation:用于修饰Controller类中的方法,生成接口方法相关文档信息
  • @ApiParam:用于修饰接口中的参数,生成接口参数相关文档信息
  • @ApiModelProperty:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息

整合Swagger

添加项目依赖

SpringBoot版本选择的是2.6.x, 在pom.xml中新增Swagger依赖

image-20220801134726733

复制代码
1
2
3
4
5
6
7
<!--Swagger3 API文档生产工具--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>

路径匹配处理

Springfox使用的路径匹配基于AntPathMatcher,而Spring Boot 2.6.x 使用的是PathPatternMatcher

方法一:启动类添加注解@EnableWebMvc

image-20220801143124229

方法二:配置文件中添加mvc默认的路径匹配策略

复制代码
1
2
3
4
mvc: # mvc默认的路径匹配策略:ANT_PATH_MATCHER pathmatch: matching-strategy: ANT_PATH_MATCHER

添加Swagger配置

注意:Swagger对生成API文档的范围有三种不同的选择

  • 生成指定包下面的类的API文档
  • 生成存在@Api注解的类的API文档
  • 生成存在@ApiOperation指定注解的方法的API文档
复制代码
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
package com.test.config; import org.springframework.beans.BeansException; import org.springframework.beans.factory.config.BeanPostProcessor; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.util.ReflectionUtils; import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.spring.web.plugins.WebFluxRequestHandlerProvider; import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider; import java.lang.reflect.Field; import java.util.List; import java.util.stream.Collectors; /** * Swagger2API接口文档配置 * Created by YuanJW on 2022/8/1. */ @Configuration @EnableOpenApi public class SwaggerConfig { /** * 创建API * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 是否启用Swagger .enable(true) // 创建API基本信息 .apiInfo(apiInfo()) // 设置Swagger暴露接口 .select() // 为指定包下Controller类生成API文档 .apis(RequestHandlerSelectors.basePackage("com.test.controller")) // 为存在@Api注解的Controller生成API文档 // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 为存在@ApiOperation注解的方法生成API文档 // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 指定处理路径 PathSelectors.any():代表所有路径 .paths(PathSelectors.any()) .build(); } /** * 自定义展示的信息 * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() // 标题 .title("SwaggerUI For borrow") // 描述 .description("cloud-borrow") // 联系 .contact(new Contact("XiaoYuanJW", "https://xiaoyuanjw.github.io/", "xxx@qq.com")) // 版本 .version("1.0") .build(); } /** * 解决Springboot2.6和Springfox不兼容问题 * @return */ @Bean public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() { return new BeanPostProcessor() { @Override public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException { if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) { customizeSpringfoxHandlerMappings(getHandlerMappings(bean)); } return bean; } private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) { List<T> copy = mappings.stream() .filter(mapping -> mapping.getPatternParser() == null) .collect(Collectors.toList()); mappings.clear(); mappings.addAll(copy); } @SuppressWarnings("unchecked") private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) { try { Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings"); field.setAccessible(true); return (List<RequestMappingInfoHandlerMapping>) field.get(bean); } catch (IllegalArgumentException | IllegalAccessException e) { throw new IllegalStateException(e); } } }; } }

实体类添加Swagger注解

复制代码
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
package com.test.entity; import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Data; /** * Created by YuanJW on 2022/5/29. */ @Data @AllArgsConstructor public class Borrow { @ApiModelProperty(value = "借阅id") Long id; @ApiModelProperty(value = "用户id") Long uid; @ApiModelProperty(value = "图书id") Long bid; }

Controller添加Swagger注解

复制代码
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
package com.test.controller; import com.alibaba.csp.sentinel.annotation.SentinelResource; import com.alibaba.fastjson.JSONObject; import com.test.entity.*; import com.test.service.BorrowService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; /** * Created by YuanJW on 2022/5/29. */ @Api(tags = "BorrowController", description = "借阅信息管理") @RestController @RequestMapping("/borrow") @Slf4j public class BorrowController { @Resource BorrowService borrowService; @ApiOperation("根据用户id获取借阅信息") @GetMapping(value = "/user/{uid}", produces = "application/json;charset=UTF-8") public UserBorrowDetail getBorrowByUser(@PathVariable("uid") @ApiParam("用户id") Long uid){ return borrowService.getBorrowByUser(uid); } @ApiOperation("根据图书id获取借阅信息") @GetMapping(value = "/book/{bid}", produces = "application/json;charset=UTF-8") public BookBorrowDetail getBorrowByBook(@PathVariable("bid") @ApiParam("图书id") Long bid){ return borrowService.getBorrowByBook(bid); } @ApiOperation("根据用户id和图书id获取借阅信息") @GetMapping(value = "/getborrow", produces = "application/json;charset=UTF-8") public BorrowDetail getBorrow(@RequestParam(value = "uid", required = true) @ApiParam("用户id") Long uid, @RequestParam(value = "bid", required = true) @ApiParam("图书id") Long bid){ return borrowService.getBorrow(uid, bid); } @ApiOperation("图书借阅") @PostMapping(value = "/{uid}/{bid}", produces = "application/json;charset=UTF-8") public JSONObject borrow(@PathVariable("uid") @ApiParam("用户id") Long uid, @PathVariable("bid") @ApiParam("图书id") Long bid) { // 添加借阅信息 boolean result = borrowService.borrow(uid, bid); // 创建JSON对象并返回 JSONObject jsonObject = new JSONObject(); if (result) { jsonObject.put("code", 200); jsonObject.put("success", true); jsonObject.put("message", "借阅成功"); return jsonObject; } jsonObject.put("code", 100); jsonObject.put("success", false); jsonObject.put("message", "借阅失败"); return jsonObject; } }

运行测试

运行服务并访问:http://localhost:8301/swagger-ui/index.html#/

image-20220801161312258

最后

以上就是怕孤独高山最近收集整理的关于SpringBoot集成SwaggerSpringBoot集成Swagger的全部内容,更多相关SpringBoot集成SwaggerSpringBoot集成Swagger内容请搜索靠谱客的其他文章。

本图文内容来源于网友提供,作为学习参考使用,或来自网络收集整理,版权属于原作者所有。
点赞(88)

评论列表共有 0 条评论

立即
投稿
返回
顶部