Springboot集成Swagger接口api

1.Swagger是什么

Swagger是一套基于OpenAPI规范构建的开源工具，可以帮助我们设计、构建、记录以及使用Rest API。Swagger主要包括了一下三个部分：

• Swagger Editor: 基于浏览器的编辑器，我们可以使用它来编写我们的OpenAPI文档。
• Swagger UI: 它会将我们编写的OpenAPI规范呈现为交互式的API文档。后文我们将使用浏览器来查看并且操作我们的Rest
  API。
• Swagger CodeGen：它可以通过为OpenAPI规范定义的任何API生成服务器存根和客户端SDK来简化构建过程。

2.为什么要用Swagger

降低开发人员对接口文档的维护成本

3.SpringBoot使用swagger姿势

3.1 引入依赖

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

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

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

3.2 SwaggerConfig配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("study-demo api")
                .contact(new Contact("authorname", "xxx@xxx.com", ""))
                .version("1.0")
                .build();
    }
 }

3.3 编写接口

AuthController提供了登录用户信息查询接口

@Api(tags = "用户会话")
@RestController
@RequestMapping("auth")
public class AuthController {

    @ApiOperation(value = "用户信息接口", notes = "查看当前登录用户信息")
    @GetMapping("userInfo")
    public JsonResult<LoginUserDTO> loginUserDTO() {

        return JsonResult.success(SessionContextHolder.getUserInfo());
    }
}

LoginUserDTO 实体类代码

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ApiModel("登录用户信息")
public class LoginUserDTO {

    @ApiModelProperty("用户姓名")
    private String name;

    @ApiModelProperty("用户手机号")
    private String mobile;
}

3.4 验证接口文档

4.相关注解详解

4.1 通过在控制器类添加@Api注解，设置接口描述信息

@Api(tags = "用户会话")
@RestController
@RequestMapping("auth")
public class AuthController {}

4.2 通过在接口方法上添加@ApiOperation注解来说明接口

 @ApiOperation(value = "用户信息接口", notes = "查看当前登录用户信息")
 @GetMapping("userInfo")
 public JsonResult<LoginUserDTO> loginUserDTO() {

     return JsonResult.success(SessionContextHolder.getUserInfo());
 }

4.3 通过在实体类上添加@ApiModel和@ApiModelProperty注解来描述数据模型

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ApiModel("登录用户信息")
public class LoginUserDTO {

    @ApiModelProperty("用户姓名")
    private String name;

    @ApiModelProperty("用户手机号")
    private String mobile;
}

4.4 文档信息配置描述

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // 配置Swagger的Docket的bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // RequestHandlerSelectors配置扫描接口的方式
                .apis(RequestHandlerSelectors.any())
                // path过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("study-demo api")
                .contact(new Contact("xxxusername", "wwww.xxx.com", "xxx@126.com"))
                .version("1.0")
                .build();
    }

4.5 接口过滤

1、加注解：如果想在文档中屏蔽掉某个接口方法，只需要在该接口方法上添加@ApiIgnore即可
2、在Docket上增加筛选。Docket提供了apis()和paths()两个方法来帮助我们在不同级别上过滤接口：
apis(): 这种方式我们可以通过指定包名的方式，让Swagger 只去某些包下扫描。
paths(): 这种方式可以通过筛选API的 url 来进行过滤。

4.6 文档开关，配置是否开启swagger文档

因为swagger能快速生成文档，且能直接文档上调用接口，如果在生产环境暴露接口文档，那是非常危险的事情，所以我们需要在不同环境决定是否开启文档

springfox.documentation.enabled=true
springfox.documentation.swagger-ui.enabled=false