springboot配置 Swagger2 接口文档引擎

朱雀 2021-03-24 15:07 654阅读 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);
        }

### 5. 查看文档 ###

地址：[http://ip][http_ip]:port/swagger-ui.html  
可以在这里进行接口的测试  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0ODM4NjQz_size_16_color_FFFFFF_t_70]

[http_ip]: http://ip
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0ODM4NjQz_size_16_color_FFFFFF_t_70]: /images/20210324/1616598435137.png