【微服务架构 - 13 - Swagger2】01 配置 Swagger2 接口文档引擎

pom.xml

---

<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>

配置 Swagger2

---

创建一个名为 Swagger2Config 的 Java 配置类，代码如下：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Classname Swagger2Config
 * @Date 2019/3/6 14:08
 * @Created by Yuu
 */
@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yuu.itoken.service.admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("iToken 管理员 API 文档")
                .description("iToken 管理员 API 网关接口")
                .version("1.0.0")
                .build();
    }
}

启用 Swagger2

---

Application 中加上注解 @EnableSwagger2 表示开启 Swagger2

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;


/**
 * @Classname ServiceAdminApplication
 * @Date 2019/2/25 11:16
 * @Created by Yuu
 */
@SpringBootApplication(scanBasePackages = "com.yuu.itoken")
@EnableEurekaClient
@EnableSwagger2
@MapperScan(basePackages = {"com.yuu.itoken.common.mapper", "com.yuu.itoken.service.admin.mapper"})
public class ServiceAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceAdminApplication.class, args);
    }
}

使用 Swagger2

在 Controller 中增加 Swagger2 相关注解

   /**
     * 分页查询
     *
     * @param pageNum
     * @param pageSize
     * @param tbSysUserJson
     * @return
     * @throws Exception
     */
    @ApiOperation(value = "管理员分页查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "pageSize", value = "笔数", required = true, dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "tbSysUserJson", value = "管理员对象 JSON 字符串", required = false, dataTypeClass = String.class, paramType = "json")
    })
    @RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
    public BaseResult page(
            @PathVariable(required = true) int pageNum,
            @PathVariable(required = true) int pageSize,
            @PathVariable(required = false) String tbSysUserJson
    ) throws Exception {

        TbSysUser tbSysUser = null;
        if (tbSysUserJson != null) {
            tbSysUser = MapperUtils.json2pojo(tbSysUserJson, TbSysUser.class);
        }

        PageInfo pageInfo = adminService.page(pageNum, pageSize, tbSysUser);

        // 分页后查询的结果
        List list = pageInfo.getList();

        // 封装 Cursor 对象
        BaseResult.Cursor cursor = new BaseResult.Cursor();
        cursor.setTotal(new Long(pageInfo.getTotal()).intValue());
        cursor.setLimit(pageInfo.getPageNum());
        cursor.setOffset(pageInfo.getPageSize());

        return BaseResult.ok(list, cursor);
    }

Swagger 注解说明

---

• @Api ：修饰整个类，描述 Controller 的作用
• @ApiOperation ：描述一个类的一个方法，或者说一个接口
• @ApiParam ：单个参数描述
• @ApiModel ：用对象来接收参数
• @ApiProperty ：用对象接收参数时，描述对象的一个字段
• @ApiResponse ：HTTP 响应其中 1 个描述
• @ApiResponses ：HTTP 响应整体描述
• @ApiIgnore ：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam ：一个请求参数
• @ApiImplicitParams ：多个请求参数

访问 Swagger2

---

访问地址： http://ip:port/swagger-ui.html