Swagger2配置类详解

Swagger2配置类详解

1、需要引入的jar包

<!--swagger依赖(pojo注解)-->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.20</version>
</dependency>

<!--生成后端开发文档-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<!--第三方生成后端开发文档页面UI-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2、Swagger配置类讲解

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                // 通过调用自定义方法apiInfo，获得文档的主要信息
                .apiInfo(apiInfo())
                // 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
                .select()
                // 扫描指定包
                .apis(RequestHandlerSelectors.basePackage("com.lk.bootsecuritystarter.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/doc.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 接口文档标题
                .title("接口文档")
                // 对于接口文档的相关描述
                .description("接口文档")
                // 接口文档内容的一下补充
                .contact(new Contact("用户名", "http://localhost:8888/doc.html", "邮箱"))
                // 版本
                .version("1.0")
                .build();
    }
}

3、Swagger的注解及应用场景

3.1.@Api

　　@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源，使用方式代码如下所示。

@Api(tags={"用户接口"})
@RestController
public class UserController {
}

3.2.ApiParam

　　@ApiParam 用于 Controller 中方法的参数说明。使用方式代码如下所示。

@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
    System.err.println(param.getName());
    return new UserDto();
}

3.3.ApiOperation

　　@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。使用方式代码如下所示

@ApiOperation(value="新增用户", notes="详细描述")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {

}

3.4.ApiModel

　　@ApiModel 用在实体类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示。

@ApiModel(value = "com.znzz.user", description = "新增用户参数")
public class AddUserParam {
}

3.5.ApiModelProperty

　　@ApiModelProperty() 用于字段，表示对 model 属性的说明。使用方式代码如下所示。

@Data
@ApiModel(value = "com.znzz.user", description = "新增用户参数")
public class AddUserParam {
    @ApiModelProperty(value = "ID")
    private String id;
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;
}