SpringBoot引入Knife4j(增强版Swagger)为Java MVC框架生成api文档-CFANZ编程社区

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", "answer_ljm@163.com"))
                .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自动配置