Springboot整合Swagger

swagger是一个用于生成服务器接口的规范性文档、并能够对接口进行测试的工具

1. 整合swagger

1.1 添加依赖

• swagger2

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

• swagger UI

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

1.2 配置（java配置方式）

• 创建config目录以及SwaggerConfig配置类
  
• 编写SwaggerConfig类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * swagger会帮组我们生成文档
     * 1. 配置生成的文档信息
     * 2. 配置生成的规则
     */

    /*Docket封装接口文档信息*/
    @Bean
    public Docket getDocket() {

        // 创建封面信息对象
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();

        // 设置文档标题、描述、联系人
        apiInfoBuilder.title("平台接口说明文档")
                .description("此文档说明了平台后端接口规范")
                .version("v 1.0.0")
                .contact(new Contact("chen_cheng", "www.chen_cheng.com","chen_cheng@qq.com"));

        ApiInfo apiInfo = apiInfoBuilder.build();

        // 指定文档风格
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo) // 指定生成的文档中的封面信息；文档标题、版本、作者
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.computerskills.competition.controller"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }
 }

• 访问swagger接口文档

http://localhost:8080/swagger-ui.html
在路径后添加swagger-ui.html即可

2. swagger注解说明

swagger提供了一套注解，可以对每个接口进行详细说明

• @Api类注解，在控制器类添加此注解，可以对控制器类进行功能说明
  比如：
  在RoleController类添加：

@Api(value = "提供添加角色、查询角色的功能", tags = "角色管理")

• @ApiOperation方法注解，说明接口方法的作用
  比如：
  在RoleController类中的方法添加：

@ApiOperation("添加角色接口")

• @ApiImplicitParams和@ApiImplicitParam方法注解，说明接口方法的参数
  比如：
  在RoleController类中的方法添加：

 @ApiImplicitParams({
         @ApiImplicitParam(dataType = "string", name = "rName",value = "角色名称",required = true),
         @ApiImplicitParam(dataType = "string", name = "rDesc",value = "角色描述",required = false,defaultValue = "")
 })

• @ApiModel和@ApiModeProperty 当接口参数和返回值为对象类型时，在实体类中添加注解说明
  比如：
  在Role类中的方法添加：

/**
 * 角色信息
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
@ToString
@ApiModel(value = "Role对象", description = "角色信息")
public class Role {

    @ApiModelProperty(dataType = "int",required = false)
    private int rId;
    @ApiModelProperty(dataType = "string",required = true,value = "角色名称")
    private String rName;
    @ApiModelProperty(dataType = "string",required = false,value = "角色描述信息")
    private String rDesc;
}

• @ApiIgnore接口方法注解，添加此注解的方法将不会生成到接口文档中
  比如：
  在RoleController类中的addRole方法添加：

@ApiIgnore

3.swagger-ui插件

swagger默认界面：

默认访问路径：http://localhost:8080/swagger-ui.html

修改swagger文档界面：

• 导入依赖

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

• 访问路径
  http://localhost:8080/doc.html#/
• 界面