SpringBoot开发工具包

Swagger2

简介

Swagger2是一个用于生成、展示和测试API文档的工具，它可以帮助开发者更好地了解和使用API接口

使用

1. 添加Swagger2的依赖：在项目的pom.xml文件中添加Swagger2的依赖。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>最新版本</version>
</dependency>

2. 配置Swagger2：创建一个配置类，例如SwaggerConfig，用于配置Swagger2相关的参数

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 设置扫描的包路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("示例项目的接口文档")
                .version("1.0.0")
                .build();
    }
}

在上面的示例中，api()方法用于创建Docket对象，并通过.apis()方法指定需要扫描的Controller所在的包路径。你需要将com.example.controller替换为你实际的包路径。
3. 启动应用程序：启动Spring Boot应用程序，访问地址：http://localhost:端口号/swagger-ui.html，即可查看生成的Swagger2接口文档页面。

注解

@Api

用于对Controller进行分类或者说明

@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {
    // ...
}

@ApiOperation

用于对单个方法进行描述和说明。

@ApiOperation(value = "获取所有用户", notes = "返回所有用户列表")
@GetMapping("/")
public List<User> getAllUsers() {
    // ...
}

@ApiParam

用于对方法的参数进行详细说明。

@ApiOperation(value = "根据ID获取用户", notes = "根据用户ID查询用户信息")
@GetMapping("/{id}")
public User getUserById(@ApiParam(value = "用户ID", example = "1") @PathVariable Long id) {
    // ...
}

@ApiModel

用于对实体类或DTO进行说明。

@ApiModel(description = "用户信息")
public class User {
    // ...
}

@ApiModelProperty

用于对实体类属性进行详细说明。

@ApiModel(description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户名", example = "john")
    private String username;
    
    // ...
}

@ApiIgnore

用于指定不在Swagger文档中显示的方法或类。

@ApiOperation(value = "忽略该接口")
@ApiIgnore
@GetMapping("/ignore")
public void ignoredMethod() {
    // ...
}

@ApiResponses

用于对接口响应进行描述。

@ApiResponse

用于对单个方法的响应进行描述。

@ApiOperation(value = "保存用户", notes = "保存用户信息")
@ApiResponses({
    @ApiResponse(code = 200, message = "保存成功"),
    @ApiResponse(code = 400, message = "请求参数错误"),
})
@PostMapping("/")
public void saveUser(@RequestBody User user) {
    // ...
}

@ApiParamImplicit

用于对方法的参数进行隐式说明。

@ApiOperation(value = "根据名称搜索用户", notes = "根据名称模糊匹配用户信息")
@GetMapping("/search")
public List<User> searchUsers(@ApiParamImplicit(name = "name", value = "用户名") @RequestParam String name) {
    // ...
}

@ApiModelProperty

用于对实体类属性进行更详细的说明。

@ApiModelProperty(
    value = "用户状态",
    allowableValues = "ACTIVE, INACTIVE",
    example = "ACTIVE"
)
private String status;

@ApiError

用于定义错误响应的详细信息。

@ApiError(code = 400, reason = "请求参数有误")
@PostMapping("/")
public void saveUser(@RequestBody User user) {
    // ...
}

@ApiImplicitParam

用于对方法的参数进行隐式的描述，一般用于描述请求Header中的参数。

@ApiOperation(value = "获取用户信息", notes = "根据用户名获取用户信息")
@ApiImplicitParam(name = "Authorization", value = "访问令牌", required = true, paramType = "header")
@GetMapping("/{username}")
public User getUserByUsername(@PathVariable String username) {
    // ...
}

@ApiImplicitParams

用于对方法的多个参数进行隐式的描述。

@ApiOperation(value = "更新用户信息", notes = "根据用户ID更新用户信息")
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "用户ID", example = "1", required = true, dataType = "Long", paramType = "path"),
    @ApiImplicitParam(name = "user", value = "用户信息", dataType = "User", paramType = "body")
})
@PutMapping("/{id}")
public void updateUser(@PathVariable Long id, @RequestBody User user) {
    // ...
}

@ApiIgnoreProperties

用于指定在Swagger文档中忽略某个实体类属性。

@ApiModel(description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户名", example = "john")
    private String username;
    
    @ApiModelProperty(hidden = true)
    private String password; // 隐藏密码属性

    // ...
}

Knife4j

简介

Knife4j是一个基于Swagger的Java接口文档生成工具，它提供了一种简单、便捷的方式来创建和维护API文档。Knife4j通过解析代码注释和API接口定义，自动生成可视化的接口文档页面，帮助开发者更好地理解和使用接口。

一些主要的特性和功能包括：

• 自动生成文档：通过解析代码注释和API接口定义，自动生成接口文档，无需手动编写文档。
• 可视化界面：提供直观的UI界面展示API文档，支持搜索、分组、排序等功能，方便查看和检索接口信息。
• 参数校验和模拟测试：支持对接口参数进行校验和模拟测试，验证接口的输入和输出数据。
• 接口权限控制：支持配置接口访问权限，控制不同用户或角色的接口访问权限。
• 在线调试接口：提供在线调试工具，可以直接在文档中执行接口请求，方便开发者进行接口测试和调试。
  通过Knife4j，开发者可以减少编写和维护接口文档的工作量，并提供直观、友好的界面来浏览和调试接口。同时，Knife4j还支持集成到Spring Boot、Spring Cloud等常用开发框架中，提供更便捷的接口文档管理和使用方式。

使用

在Spring Boot中使用Knife4j可以按照以下步骤进行：

1. 添加Knife4j的依赖：在项目的pom.xml文件中添加Knife4j的依赖。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>最新版本</version>
</dependency>

2. 配置Swagger2
3. 启动应用程序：启动Spring Boot应用程序，访问地址：http://localhost:端口号/doc.html，即可查看生成的Knife4j接口文档页面。