接口文档 Knife4j

1.pom

点击查看代码

<!-- 只需这一行即可，其他 starter 自带 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

2.yml

点击查看代码

springdoc:
  swagger-ui:
    path: /swagger-ui.html   # UI 访问地址
    tags-sorter: alpha       # 标签按字母排序
  api-docs:
    path: /v3/api-docs       # 原始 OpenAPI json

knife4j:
  enable: true               # 总开关
  setting:
    language: zh_cn          # 中文界面
    enable-footer: false     # 去掉底部版权
  basic:
    enable: true
    username: admin
    password: 123456

3.配置类

点击查看代码

@Configuration
public class Knife4jConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Spring Boot 3 接口文档")
                .version("1.0.0")
                .description("基于 Knife4j 的在线 API")
                .license(new License().name("Apache 2.0").url("https://springdoc.org")));
    }
}

4.常用注解

Swagger2 老注解	OpenAPI3 新注解	说明
@Api	@Tag	给 Controller 分组
@ApiOperation	@Operation	描述单个接口
@ApiParam	@Parameter	描述请求参数
@ApiModel	@Schema	描述实体类

点击查看代码

@RestController
@RequestMapping("/user")
@Tag(name = "用户模块")
public class UserController {

    @PostMapping("/login")
    @Operation(summary = "用户登录")
    public Result<String> login(
        @Parameter(description = "用户名") @RequestParam String username,
        @Parameter(description = "密码") @RequestParam String password) {
        // ...
        return Result.success("token");
    }
}

5. 登录
   http://localhost:8080/doc.html
   http://localhost:8080/swagger-ui.html