手把手教会如何掌握Swagger

---

前言

Swagger是一个用于设计、构建、文档化和消费RESTful Web服务的开源工具集。它的主要目标是简化API的开发和维护，同时提供自动生成的交互式API文档。

---

一、Swagger重要组件及作用

1.SWAGGER官网主要提供了几种开源工具：

• Swagger Codegen: 通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的SwaggerEditor中在线生成。
• Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
• Swagger Editor:类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
• Swagger Inspector: 和postman差不多，是一个可以对接口进行测试的在线版的postman。比在SwaggerUI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
• Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
• Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。其实swagger是有两个版本的，区别还挺大的，一个是swagger-ui也就是swagger1;还有一个是springfox-swagger也就是swagger2;

2.Swagger的优点：

• 自动文档生成： Swagger可以自动生成API文档，减少了手动编写文档的工作量，并保持文档与实际API的同步。
• 易于使用： Swagger提供了直观的界面，使开发人员能够轻松了解和测试API。
• 提高开发效率： 自动生成的客户端和服务器端代码可以节省开发时间，减少了潜在的错误。
• 标准化： Swagger采用标准的OpenAPI规范，有助于在不同的开发团队和工具之间实现互操作性。
• 支持多种编程语言： Swagger支持多种编程语言和框架，使其适用于各种技术栈的项目。

---

二、SpringBoot集成Swagger

1.环境准备

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>

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

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

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

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

1.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.配置Swagger

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

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

2.2.通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
        Contact contact = new Contact("杨树林", "http://yangshulin.com/联系人访问链接", "[email protected]");

        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://apesource.com", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

2.3.Docket 实例关联上 apiInfo()

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

2.4.重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

3.配置Swagger扫描接口

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();
}

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

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

• any()： 扫描所有，项目中的所有接口都会被扫描到
• none()： 不扫描接口
• withMethodAnnotation(final Class annotation)：通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
• withClassAnnotation(final Class annotation)：通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求

3.4可以配置接口扫描过滤
.paths(PathSelectors.ant(“/apesource/**”))
配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
除了ant还有一些配置：

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

4.配置API分组

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

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

4.2配置多个分组只需要配置多个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");
  }

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>

虽然ui界面不同，但功能是相同！

---

三、常用注解

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

1.接口注解

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

@RequestMapping("/user")
@Api(tags = "UserController|一个用来测试swagger注解的控制器1",value = "/user")
public class UserController {
}

2.方法及参数注解

在高版主的Swagger中，Swagger会自动帮我们识别简单的参数及请求信息：

1. @ApiOperation：描述一个类的一个方法，说明方法的作用
   语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

	@GetMapping(value ="/findByName")
    @ApiOperation(value="根据用户名查询", notes="描述的具体信息可以省略",httpMethod="GET",response = Result.class)
    public Result findByName(@RequestParam String userName){
    }

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

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

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

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

6. @ApiResponse：HTTP响应其中1个描述,响应配置
   语法：@ApiResponse(code = 400, message = “Invalid user supplied”)

7. @ApiResponses：HTTP响应整体描述
   语法：@ApiResponses({ @ApiResponse(code = 400, message = “Invalid Order”) })

3.实体类注解

1. @ApiModel：用对象实体来作为入参；
2. @ApiModelProperty:用于描述字段信息；
3. @ApiProperty：用对象接实体收参数时，描述对象的一个字段；
4. @ApiIgnore：使用该注解忽略这个API；
5. @ApiError ：发生错误返回的信息。

@ApiModel(value = "控制器方法返回值",description = "自定义结果集")
public class Result {
    @ApiModelProperty(name = "falge",value = "结果集状态",example = "true")
    private boolean falge;//状态
    @ApiModelProperty(name = "message",value = "提示信息",example = "查询成功")
    private String message;//提示信息
    @ApiModelProperty(name = "data",value = "返回数据")
    private Object data;//返回数据

}

效果如图：

总结

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