springboot swagger配置（SpringBoot整合Swagger方便后端测试）

用Swagger能够在后端写好接口后进行测试，测试过程非常方便。

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。

PS：Swagger 遵循了 OpenAPI 规范，OpenAPI 是 Linux 基金会的一个项目，试图通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程。

Swagger 官网地址：https://swagger.io/

Swagger 有什么用？

从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：

0. 将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；
1. 当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；
2. 通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本。

访问网址

swagger2是：http://localhost:8080/swagger-ui.html

swagger3是：http://localhost:8080/swagger-ui/index.html

常用注解

注意观察：swagger2的注解基本都是以API开头的，以此来判断注解是否为swagger2注解。同样,swagger3也有类似特性。

swagger2	swagger3	注解位置
@Api(tags=“接口描述”)	@Api(tags=“接口描述”)	controller类上
@ApiOperation(value = “接口方法描述”)	@Operation(summary = “接口方法描述”)	controller 方法上
@ApiModelProperty(value = “字段描述”)	@ApiModelProperty(value = “字段描述”)	javaBean的字段上
@ApiModel(“实体类的描述”)	@ApiModel(“实体类的描述”)	JavaBean上
@EnableSwagger2	@EnableOpenApi	配置类上
@ApiImplicitParams	@ApiImplicitParams	controller的方法参数中
@ApiImplicitParam	@ApiImplicitParam	@ApiImplicitParams 下的的子参数
@ApiParam(name = “参数描述”)	@Parameter(description = “参数描述”)	controller 方法的参数中

Swagger2的使用引入依赖

swagger2必须要引入springfox-swagger2、springfox-swagger-ui这两个依赖

lombok插件要引入lombok依赖

<!--swagger依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <!--swagger ui--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>

创建配置类

import com.google.common.base.Predicates; import org.springframework.context.Annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; 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.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("webApi") .apiInfo(webApiInfo()) .select() .paths(Predicates.not(PathSelectors.regex("/error.*"))) // .apis(RequestHandlerSelectors.basePackage("com.it")) .build(); } private ApiInfo webApiInfo(){ return new ApiInfoBuilder() .title("网站-中心API文档") .description("本文档描述了接口定义") .version("1.0") .contact(new Contact("hello", "hello","6666666666@qq.com")) .build(); } }

这样swagger就配置完成了，接下来是使用方式

使用

在entity实体类上使用

@Data public class User { @ApiModelProperty(value = "id") private String id; @ApiModelProperty(value = "用户名") private String userName; @ApiModelProperty(value = "年龄") private int age; }

在controller实体类上使用

package com.it.controller; import com.it.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; @Api(tags = "欢迎来到") @RestController @RequestMapping("/hello") public class swaggerController { @ApiOperation(value = "写在方法上的1") @GetMapping("/getTest") public User get(User user){ return user; } @PostMapping("post") public User post(User user){ return user; } @DeleteMapping("delete") public User delete(User user) { return user; } @PutMapping ("put") public User put(User user) { return user; } }

访问地址

http://localhost:8080/swagger-ui.html

图示

输入内容后，点击try it out ，即可得到结果

swagger2使用起来非常方便，引入依赖，创建一个配置类就能直接用了，用postman还得手动创建每个访问链接，非常麻烦，swagger2算是挺方便了。

swagger3

它与swagger2的差异在于

配置文件上添加的注解是@EnableOpenApi而swagger2是@EnableSwagger2 访问地址http://localhost:8080/swagger-ui/index.html 而swagger2是http://localhost:8080/swagger-ui.html pom引入的文件只有一个 springfox-boot-starter 而swagger2有两个springfox-swagger2 springfox-swagger-ui

引入依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>

加入配置类

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.http.HttpMethod; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import springfox.documentation.builders.*; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import java.util.ArrayList; import java.util.List; @EnableOpenApi //启用swagger @Configuration public class Swagger3Config implements WebMvcConfigurer { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() //.apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) //只有在接口上加了Operation注解才展示 .paths(PathSelectors.any()) .build() //.globalRequestParameters(getGlobalRequestParameters()) .globalResponses(HttpMethod.GET, getGlobalResonseMessage()) .globalResponses(HttpMethod.POST, getGlobalResonseMessage()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger3接口文档") .description("联系") .contact(new Contact("牧歌ing", "https://blog.csdn.net/u013010499", "666666@qq.com")) .version("1.0") .build(); } private List<Response> getGlobalResonseMessage() { List<Response> responseList = new ArrayList<>(); responseList.add(new ResponseBuilder().code("404").description("找不到资源").build()); return responseList; } }

使用

entity实体类

和swagger2对比没有变化

import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel("用户") public class User { @ApiModelProperty(value = "id") private String id; @ApiModelProperty(value = "用户名") private String userName; @ApiModelProperty(value = "年龄") private int age; }

controller

import com.it.entity.User; import io.swagger.annotations.Api; import io.swagger.v3.oas.annotations.Operation; import org.springframework.web.bind.annotation.*; @Api(tags="欢迎接口11") @RestController @RequestMapping("/hello1") public class HelloController { @Operation(summary = "一个Rest") //接口的备注信息 @RequestMapping(value = "request",method = RequestMethod.GET) public User rest(User user){ return user; } @Operation(summary = "一个Get") //接口的备注信息 @GetMapping("get") public User get(User user){ return user; } @PostMapping("post") public User post(User user){ return user; } @DeleteMapping("delete") public User delete(User user) { return user; } @PutMapping ("put") public User put(User user) { return user; } }

appication.properties

# 在测试环境中用到，生产环境需设置为false springfox.documentation.swagger-ui.enabled=true

访问网址：http://localhost:8080/swagger-ui/index.html

可以看到,ui变大变好看了点

,