安装

<dependencyManagement>
    <dependencies>
        <!-- Knife4J 接口文档增强 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Knife4J 接口文档增强 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

• 新建 Knife4jConfig.java 文件

/**
 * swagger config for open api.
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig implements WebMvcConfigurer {
    /**
     * 用于读取配置文件 application.properties 中 swagger 属性是否开启
     */
    @Value("${knife4j.enabled}")
    private Boolean swaggerEnabled;


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 是否开启swagger
                .enable(swaggerEnabled)
                .select()
                // 过滤条件，扫描指定路径下的文件
                .apis(RequestHandlerSelectors.basePackage("com.eezd.main.web"))
                // 指定路径处理，PathSelectors.any()代表不过滤任何路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Knife4j 4.4.x & Spring Boot 2.7 & Swagger2")
                .description("Knife4j 4.4.x & Spring Boot 2.7 & Swagger2")
                .termsOfServiceUrl("https://134333.xyz/")
                .contact(new Contact("接口文档", "https://134333.xyz", "eezd@outlook.com"))
                .version("")
                .build();
    }
}

@Api

• @Api: 对 类 进行描述

@RestController  
@Slf4j  
@Api(tags = "hello")  
public class HelloController {}

@ApiOperation

• @ApiOperation: 对 请求 进行描述

@RestController  
@Slf4j  
@Api(tags = "hello")  
public class HelloController {

    @GetMapping("/")
    @ApiOperation(value = "hello", notes = "hello测试模块")
    public String hello() {
        return "Hello World";
    }
}

对请求参数进行描述

有两种方式可以描述

• 第一种: @ApiImplicitParams + @ApiImplicitParam
  • name: 参数名
  • value: 参数说明描述
  • dataType: 类型, 默认 string
    • __file: 文件类型
    • string
    • int
    • array
    • 如果需要表示数组, 请查看最下面的 allowMultiple 数组参数
  • required: 是否是必传
  • paramType: 参数获取方式
    • header »> @RequestHeader
    • query »> @RequestParam
    • path »> @PathVariable
    • body »>
    • form »>
  • example: 实例值, 点调试那里就看得到了

@ApiOperation("保存用户信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "name", value = "名字", dataType = "string", required = true, paramType = "path", example = "张三"),
        @ApiImplicitParam(name = "age", value = "年龄", dataType = "int", required = true, paramType = "query", example = "18")
})
@PostMapping("/save/{name}")
@ResponseBody
public String save(
        @PathVariable("name") String name,
        @RequestParam("age") Integer age
) {
    return name + " " + age;
}

• 第二种
  • @ApiParam: 对代码侵入比较大

@ApiOperation("保存用户信息")
@PostMapping("/save/{name}")
@ResponseBody
public String save(
        @ApiParam(value = "名字", required = true, example = "张三")
        @PathVariable("name") String name,
        @ApiParam(value = "年龄", required = true, example = "18")
        @RequestParam("age") Integer age
) {
    return name + " " + age;
}

@ApiModel

• 给模型绑定描述的

@ApiModel(value = "用户登录对象")
@Data
public class LoginBody implements Serializable {
    /**
     * 用户名
     */
    @ApiModelProperty(value = "用户名", example = "Admin")
    private String username;

    /**
     * 用户密码
     */
    @ApiModelProperty(value = "用户密码", example = "Admin123")
    private String password;

    /**
     * 验证码
     */
    @ApiModelProperty("验证码")
    private String code;

    /**
     * 唯一标识
     */
    @ApiModelProperty("唯一标识")
    private String uuid;
}

• allowableValues 可以用于限制可接受值

@ApiModel("testAge")
public class ExamSchedule{
    // 限制只能传递 1 到 11
    @ApiModelProperty(value = "用户年龄",allowableValues = "range[1,11]")
    private Integer age;

    // 限制之恶能传递 10 或 100 或 1000 这三个
    @ApiModelProperty(value = "用户年龄2",allowableValues = "10, 100, 1000")
    private Integer age2;
}

请求响应

@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})

@ApiIgnore

• 忽略在swagger文档中显示

数组参数 allowMultiple

• allowMultiple: 表示多参数

@ApiImplicitParams({
        @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "int", paramType = "query", example = "18"),
        @ApiImplicitParam(name = "inters", value = "兴趣列表", required = true, allowMultiple = true, dataType = "int", paramType = "query", example = "123"),
})
@GetMapping("/car")
public Map<String, Object>
getCar(@RequestParam("age") Integer age,
        @RequestParam("inters") List<Long> inters
) {
    Map<String, Object> map = new HashMap<>();

    // Params 信息
    map.put("age", age);    // 18
    map.put("inters", inters);  // [123,321]
    return map;
}