Swagger

Swagger

前后端分离开发，后端需要编写接⼝说明⽂档，会耗费⽐较多的时间

swagger是⼀个⽤于⽣成服务器接⼝的规范性⽂档、并且能够对接⼝进⾏测试的⼯具

1.1 作用#

• ⽣成接⼝说明⽂档
• 对接⼝进⾏测试

1.2 Swagger整合#

• 在需要的⼯程添加依赖（Swagger2 \ Swagger UI）

  <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>
  

• 创建swagger的配置类（Java配置⽅式）

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
      /*swagger会帮助我们⽣成接⼝⽂档
       * 1：配置⽣成的⽂档信息
       * 2: 配置⽣成规则*/
  	
      @Bean
      public Docket getDocket(){
          //创建封⾯信息对象
          ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
          apiInfoBuilder.title("《商城》后端接⼝说明")
                  .description("此⽂档详细说明了项⽬后端接⼝规范....")
                  .version("2.0.1")
                  .contact(new Contact("royal","https://cnblogs.com/royal6","admin@admin.com"));  //传递作者信息
          ApiInfo apiInfo = apiInfoBuilder.build();
  
          Docket docket = new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo)   //指定⽣成的⽂档中的封⾯信息：⽂档标题、 版本、作者
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.royal.fmmall.controller"))
                  .paths(PathSelectors.any()) //所有url的api文档，单独匹配使用：PathSelectors.regex("")
                  .build();
  
          return docket;
      }
  }
  

  注意：

  2022-06-08：

  • 使用springboot2.7版本配置Swagger 3.0与2.9.2抛出异常Failed to start bean 'documentationPluginsBootstrapper';，百度搜索是spring与Swagger的路径匹配冲突，未深究

  • 改为Spring Boot 2.5.6版本使用 Swagger 2.9.2版本

• 测试：

  • 启动SpringBoot应⽤，访问：http://localhost:8080/swagger-ui.html

1.3 Swagger注解说明#

swagger提供了⼀套注解，可以对每个接⼝进⾏详细说明

@Api类注解，在控制器类添加此注解，可以对控制器类进⾏功能说明

@Api(value = "提供商品添加、修改、删除及查询的相关接⼝",tags = "商品管理") 

@ApiOperation⽅法注解：说明接⼝⽅法的作⽤

@ApiImplicitParams和@ApiImplicitParam⽅法注解，说名接⼝⽅法的参数

@ApiOperation("用户登录接口")
@ApiImplicitParams({
    @ApiImplicitParam(dataType = "string",name = "username", value = "用户登录账号",required = true),
    @ApiImplicitParam(dataType = "string",name = "password", value = "用户登录密码",required = true)
})
@GetMapping("/login")
public ResultVO login(@RequestParam("username") String name,
                      @RequestParam(value = "password") String pwd){
    ResultVO resultVO = userService.checkLogin(name, pwd);
    return resultVO;
}

@ApiModel和@ApiModelProperty当接⼝参数和返回值为对象类型时，在实体类中添加注解说明

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象", description = "⽤户/买家信息")
public class User {
    @ApiModelProperty(dataType = "int", required = false)
    private int userId;
    @ApiModelProperty(dataType = "String", required = true, value = "⽤户注册账号")
    private String userName;
    @ApiModelProperty(dataType = "String", required = true, value = "⽤户注册密码")
    private String userPwd;
    @ApiModelProperty(dataType = "String", required = true, value = "⽤户真实姓名")
    private String userRealname;
    @ApiModelProperty(dataType = "String", required = true, value = "⽤户头像url")
    private String userImg;
}

@ApiIgnore接⼝⽅法注解，添加此注解的⽅法将不会⽣成到接⼝⽂档中

1.4 Swagger-ui 插件#

• 导⼊插件的依赖

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

  • ⽂档访问

    http://ip:port/doc.html

说明：Swagger-ui1.9.6后已经停止更新，作者后续作品：Knife4j