Swagger3与Swagger2的区别:
(1)、更好的UI显示
(2)、配置启动类的注解不同:
Swagger3使用 :@EnableOpenApi
Swagger2使用 :@EnableSwagger2
(3)、Swagger UI页面的访问地址不同:
Swagger3使用:“http://localhost:8080/swagger-ui/”
Swagger2使用 :“http://localhost:8080/swagger-ui.html”
(4)、Swagger3需要配置一个springfox-boot-starter的启动器,老版本不需要配置
Spring Boot 集成Swagger3的步骤:
1、在pom.xml中导入所需依赖包
使用的是Swagger3所以需要导入springfox启动器,老版本Swagger2不需要导入
<!--Swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!--Swagger3.0需要启动器-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2、若Spring Boot版本高于2.5.6需要在application.yml文件中进行路径的配置:
spring:
mvc:
path match:
matching-strategy: ant_path_matcher
3、配置Swagger的配置类:SwaggerConfig.java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
@Configuration
@EnableOpenApi //开启Swagger3
public class SwaggerConfig {
//配置多人文档
@Bean
public Docket docket1(){return new Docket(DocumentationType.OAS_30).groupName("AA");}
@Bean
public Docket docket2(){return new Docket(DocumentationType.OAS_30).groupName("BB");}
@Bean
public Docket docket3(){return new Docket(DocumentationType.OAS_30).groupName("CC");}
//配置Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.groupName("HH")
.select()
//RequestHandlerSelectors配置要扫描接口的方式
//basePackage配置要扫描的包
//any():扫描全部 none():不扫描 withClassAnnotation:扫描类上的注解,参数是-个注解的反射对象 withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.hh.controller"))
//过滤
.paths(PathSelectors.any())
.build();
}
//配置Swagger apiInfo()
private ApiInfo apiInfo(){
Contact contact = new Contact("hh","https://aabbcc.com","hh@163.com");
return new ApiInfo(
"Swagger测试",
"Swagger测试",
"v1.0",
"hh@163.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
4、创建User实体类,并使用Swagger中的注解:
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户id")
private Integer id;
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("用户密码")
private String password;
}
5、创建UserController.java控制类,并使用Swagger中的注解:
import com.hh.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
//只要我们的接口中,返回值存在实体类,就会扫描到Swagger中
@ApiOperation("User控制类")
@GetMapping(value = "/user")
public User user(@ApiParam("用户编号") @PathVariable("id") Integer id){
return new User();
}
}
6、访问http://localhost:8080/swagger-ui/:
至此完成集成Swagger
Swagger常用注解:
(1)、@Api:用在类上,描述该类的作用 (2)、@ApiOperation:用在方法上,描述方法的作用,标注在具体请求上 (3)、@ApiModel:描述一个Model的信息,用于class上 (4)、@ApiModelProperty:与@ApiModel连用,描述实体类的字段 (5)、@ApiImplicitParams:用在方法上包含一组参数说明 (6)、@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面。 (7)、@ApiResponses:用于表示一组响应 (8)、@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息