SpringBoot引入Knife4j(增強版Swagger)爲Java MVC框架生成api文檔

knife4j是爲Java MVC框架集成Swagger生成Api文檔的增強解決方案,前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一樣小巧,輕量,並且功能強悍!

 

快速開始

添加maven依賴

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.3</version>
</dependency>

配置文件配置

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("2.1版本")
                .select()
                // 這裏指定Controller掃描包路徑
                .apis(RequestHandlerSelectors.basePackage("com.jaemon.app.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("app項目接口文檔")
                .description("app項目")
                .termsOfServiceUrl("http://IP:PORT/{contextPath}/doc.html")
                .contact(new Contact("Jaemon", "http://answer", "[email protected]"))
                .license("app service")
                .licenseUrl("https://www.github.com")
                .version("1.0")
                .build();
    }
}

訪問： http://IP:PORT/{contextPath}/doc.html
eg. http://localhost:8888/oms/doc.html

 

入門使用

實體類

@Data
@ApiModel("用戶查詢請求對象")
public class UserReqDTO {
    @ApiModelProperty(notes = "用戶姓名")
    private String userName;
    @ApiModelProperty(notes = "登錄賬號")
    private String loginName;
}

@Data
@ApiModel("用戶返回視圖對象")
@AllArgsConstructor
public class UserVO {
    @ApiModelProperty(required = true, notes = "用戶id")
    private Long id;
    @ApiModelProperty(required = true, notes = "用戶姓名")
    private String userName;
    @ApiModelProperty(required = true, notes = "登錄賬號")
    private String loginName;
}

@ApiModel("通用接口返回對象")
@Data
@AllArgsConstructor
public class Result<T> {
    @ApiModelProperty(required = true, notes = "響應碼", example = "0")
    private int code;
    @ApiModelProperty(required = true, notes = "響應描述", example = "成功")
    private String msg;
    @ApiModelProperty(notes = "響應數據")
    private T data;
}

控制層

@Api(value = "", tags = "測試接口")
// 大分類順序
@ApiSort(value = 1)
@RestController
@RequestMapping(value = "/demo")
public class DemoController {
    
    @PostMapping("/userList")
    @ApiOperation(value = "userList接口", notes = "查詢用戶列表")
    @ApiResponses(value = {
            @ApiResponse(code = 0, message = "請求成功"),
            @ApiResponse(code = 1, message = "請求失敗")
    })
    public Result userList(@RequestBody UserReqDTO userReqDTO) {
        List<UserVO> userVOS = Lists.newArrayList();
        UserVO userVO;
        for (int i = 0; i < 5; i++) {
            userVO = new UserVO((long)i, "Jaemon" + i, "Jaemon" + i);
            userVOS.add(userVO);
        }

        return new Result(0, "成功", userVOS);
    }

    @ApiOperation(value = "findByUserId接口", notes = "根據用戶id查詢用戶信息")
    @ApiImplicitParam(name = "id", value = "用戶id", paramType = "path")
    @GetMapping("/findByUserId/{id}")
    public Result<UserVO> findByUserId(@PathVariable("id") Long id) {
        UserVO userVO = new UserVO(id, "Jaemon", "Jaemon");

        return new Result(0, "成功", userVO);
    }

}

 

常用註解說明

• @Api： 用在類上，說明該類的作用
• @ApiOperation： 用在方法上，說明方法的作用，標註在具體請求上，value和notes的作用差不多，都是對請求進行說明；tags則是對請求進行分類的，比如你有好幾個controller，分別屬於不同的功能模塊，那這裏我們就可以使用tags來區分了，看上去很有條理
• @ApiImplicitParams： 用在方法上包含一組參數說明
• @ApiImplicitParam： 用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
  • paramType：參數放在哪個地方
  • header 請求參數的獲取：@RequestHeader
  • query 請求參數的獲取：@RequestParam
  • path（用於restful接口） 請求參數的獲取：@PathVariable
  • body（不常用）
  • form（不常用）
  • name： 參數名
  • dataType： 參數類型
  • required： 參數是否必須傳
  • value： 參數的意思
  • defaultValue： 參數的默認值
• @ApiResponses： 用於表示一組響應
• @ApiResponse： 用在@ApiResponses中，一般用於表達一個錯誤的響應信息
  • code： 數字，例如400
  • message： 信息，例如”請求參數沒填好”
  • response： 拋出異常的類
• @ApiModel： 描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam註解進行描述的時候）表明這是一個被swagger框架管理的model，用於class上
• @ApiModel： 使用在實體類上，描述實體類。
• @ApiModelProperty ： 使用在實體類上的成員變量上，描述成員變量的含義。

 

SpringCloud微服務架構中使用

在Spring Cloud的微服務架構下,每個微服務其實並不需要引入前端的Ui資源,因此在每個微服務的Spring Boot項目下,引入knife4j提供的微服務starter

<dependency>    
 <groupId>com.github.xiaoymin</groupId>    
 <artifactId>knife4j-micro-spring-boot-starter</artifactId>    
 <version>${knife4j.version}</version>
</dependency>

在網關聚合文檔服務下,可以再把前端的ui資源引入

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-spring-boot-starter</artifactId>    
  <version>${knife4j.version}</version>
</dependency>

 

Reference

• knife4j
• Swagger 增強（knife4j）自動生成Api 文檔（SpringBoot & SpringCloud Gateway自動配置