springboot配置 Swagger2 接口文档引擎-蒲公英云

springboot配置 Swagger2 接口文档引擎

朱雀 2021-03-24 15:07 737阅读 0赞

0. 关于Swagger

Swagger是一个功能强大且易于使用的API开发人员工具套件，适用于团队和个人，支持从整个API生命周期（从设计和文档到测试和部署）的开发。

1. 增加 Swagger2 所需依赖

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

2. 配置 Swagger2

创建一个名为 Swagger2Config 的 Java 配置类:

@Configuration
public class Swagger2Config { 
    @Bean
    public Docket createRestApi() { 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.funtl.itoken.service.admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() { 
        return new ApiInfoBuilder()
                .title("iToken API 文档")
                .description("iToken API 网关接口，http://www.funtl.com")
                .termsOfServiceUrl("http://www.funtl.com")
                .version("1.0.0")
                .build();
    }
}

3. 启用 Swagger2

在Application类上加上注解 @EnableSwagger2 表示开启 Swagger

4. 使用 Swagger2

eg:

/** * 类别列表分页查询 * * @param pageNum * @param pageSize * @param tbCatagory * @return */
    @ApiOperation(value = "类别列表分页查询接口")
    @ApiImplicitParams({ 
            @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int"),
            @ApiImplicitParam(name = "pageSize", value = "每页记录数", required = true, dataType = "int"),
            @ApiImplicitParam(name = "tbCatagory", value = "查询条件对象", required = false, dataTypeClass = TbCatagory.class)
    })
    @GetMapping("page/{pageNum}/{pageSize}")
    public BaseResult page(
            @PathVariable(required = true) int pageNum,
            @PathVariable(required = true) int pageSize,
            @RequestParam(required = false) TbCatagory tbCatagory
    ) throws Exception { 
        PageInfo pageInfo = catagoryService.page(pageNum, pageSize, tbCatagory);
        // 分页后的结果集
        List<TbCatagory> list = pageInfo.getList();
        // 封装 Cursor 对象
        BaseResult.Cursor cursor = new BaseResult.Cursor();
        cursor.setTotal(new Long(pageInfo.getTotal()).intValue());
        cursor.setOffset(pageInfo.getPageNum());
        cursor.setLimit(pageInfo.getPageSize());
        return BaseResult.ok(list, cursor);
    }