SpringBoot2 学习笔记07 knife4j+swagger2 接口文档注解使用方式

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

/**
 * 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", "[email protected]"))
                .version("")
                .build();
    }
}

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

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

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

@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;
}

@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(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;
}

@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 = "请求路径没有或页面跳转路径不对")
})

@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;
}