【微服務架構 - 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