前言
本篇记录使用SpringBoot整合Swagger
一、Swigger是什么?
早期的开发,大部分采取的方式:Vue + SpringBoot,Vue通过js渲染页面,后端把数据传递给js,早期前端只负责写页面,然后把写好的HTML页面给后端,后端使用模板引擎(Jsp,Thymeleaf、 freemarker)进行开发。
现在公司大部分的业务都使用前后端分离进行开发,相对于混合开发来说,前后端分离拥有很大的优势
前后端分离的好处:各自开发,相对独立,松耦合,前后端通过API进行交互,后端提供接口给前端,前端去调用该接口,但可能会导致前后端团队人员不能做到及时协商,出现一些问题。解决方式:早期使用实时更新文档,但非常繁琐,后来又使用postman来进行一些测试。
现在开发,很多采用前后端分离的模式,前端只负责调用接口,进行渲染,前端和后端的唯一联系,变成了API接口。因此,API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架,而且swagger可以模拟http请求调用。
二、使用步骤
1.引入依赖
在创建的SpringBoot项目基础上,我们需要先导入所需要的依赖。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
除了必须的依赖,需要导入swagger的依赖
2.编写配置文件
首先配置application.yml文件
#springboot2.60以上版本需要更改springmvc路径匹配规则
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
接着我们需要在项目中新建一个config包,配置swagger
package com.lzl.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
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.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.lang.reflect.Field;
import java.util.List;
import java.util.stream.Collectors;
/**
* --效率,是成功的核心关键--
*
* @Author lzl
* @Date 2023/3/7 14:57
*/
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
@Bean
public Docket createDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("dev")//组名
.apiInfo(createApiInfo());//设置api文档相关信息
//若是没有效果,则需要加上如下代码
// .select().apis(RequestHandlerSelectors.basePackage("com.qf.controller"))
// .build();
}
@Bean
public ApiInfo createApiInfo(){
return new ApiInfoBuilder()
.title("Swagger测试")
.licenseUrl("http://www.baudu.com")
.version("10.1")
.description("这是个测试Swagger的项目")
.contact(new Contact("Sincere", "项目负责人", "127.0.0.1@qq.com"))
.build();
}
@Bean
public BeanPostProcessor generateBeanPostProcessor(){
return new BeanPostProcessor() {
@Override
public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
if (bean instanceof WebMvcRequestHandlerProvider) {
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);
}
}
};
}
}
3.编写controller和实体类
package com.lzl.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/**
* --效率,是成功的核心关键--
*
* @Author lzl
* @Date 2023/3/7 15:04
*/
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户对象")
public class User {
@ApiModelProperty("用户唯一标识")
private Integer userId;
@ApiModelProperty("用户名")
private String userName;
@ApiModelProperty("家庭住址")
private String address;
}
controller
package com.lzl.controller;
import com.lzl.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
/**
* --效率,是成功的核心关键--
*
* @Author lzl
* @Date 2023/3/7 15:08
*/
@RestController
@RequestMapping("/user")
@Api(tags = "用户接口")
public class UserController {
@GetMapping("/getAll")
@ApiOperation("条件查询+分页获取用户信息")
public List<User> getAll(User user){
List<User> users = new ArrayList<>();
users.add(new User(1,"大飞","草庙村"));
users.add(new User(2,"大黄","山洞"));
users.add(new User(3,"任老板","卧龙山"));
return users;
}
@DeleteMapping("/deleteInfo")
@ApiOperation("根据ID删除用户")
public String deleteInfo(Integer id){
return "删除成功!";
}
}
4.测试
启动项目,访问http://localhost:8080/swagger-ui.html
如下:
成功
总结
Swagger主要是用于前后端的联调,本篇只是浅浅的入门使用,有不足之处请各位指出