SpringBoot集成Swagger

目录

一、Swagger能干什么？

二、SpringBoot集成Swagger

2.1 初始实现步骤

2.2 配置Swagger

2.3 配置扫描接口

2.4 配置API分组

2.5拓展：其他皮肤

三、常用注解 

---

 

一、Swagger能干什么？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

1.接口的文档在线自动生成

2.功能测试

二、SpringBoot集成Swagger

2.1 初始实现步骤

1. 添加Maven依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.编写HelloController，测试确保运行成功

3.编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
    
}

 4.访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

注意:如果启动报错空指针是因为springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错。可以在启动类上加上@EnableWebMvc注解或者在配置中切换为原先的AntPathMatcher。

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.2 配置Swagger

1.Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

2.可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://apesource.com", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

3.Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4.重启项目，访问测试 http://localhost:8080/swagger-ui.html 

2.3 配置扫描接口

1.构建Docket时通过select()方法配置怎么扫描接口

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
      .build();
}

2.重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

3.除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式

any()             // 扫描所有，项目中的所有接口都会被扫描到
none()             // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

 4.除此之外，我们还可以配置接口扫描过滤

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
      .paths(PathSelectors.ant("/apesource/**"))
      .build();
}

 5.这里的可选值还有

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

2.4 配置API分组

1.如果没有配置分组，默认是default。通过groupName()方法即可配置分组

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

2.重启项目查看分组

3.如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

2.5拓展：其他皮肤

可以导入不同的包实现不同的皮肤定义

1.默认的访问 http://localhost:8080/swagger-ui.html

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2.bootstrap-ui 访问 http://localhost:8080/doc.html

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

三、常用注解 

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用

语法：@Api(tags="说明该类的作用，可以在UI界面上看到的注解"，value = "/类的访问路径", description = "类的文字描述")

@ApiOperation：描述一个类的一个方法，说明方法的作用

语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

@ApiImplicitParam：一个请求参数

语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”

· header --> 请求参数的获取：@RequestHeader

· query --> 请求参数的获取：@RequestParam

· path（用于restful接口）--> 请求参数的获取：@PathVariable

· body（不常用）

​· form（不常用）

）

@ApiImplicitParams： 多个请求参数

@ApiParam：单个参数描述

语法：@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

@ApiResponse：HTTP响应其中1个描述,响应配置

语法：@ApiResponse(code = 400, message = "Invalid user supplied")

@ApiResponses：HTTP响应整体描述

语法：@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

@ApiModel：用对象实体来作为入参

@ApiProperty：用对象接实体收参数时，描述对象的一个字段

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息