简介

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的使用

引入依赖

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变大变好看了点