Swagger文档生成

## 一、什么是Swagger

Swagger 是一套用于设计、构建、文档化和测试 RESTful API 的开源工具集。

Swagger 提供了一种标准化的方式来描述 API 的结构、请求参数、响应格式等信息，使得前后端开发人员能够更高效地协作。

Swagger 是由 SmartBear Software 提供的一套 API 开发工具集，最初是独立的 API 规范，现在已成为 OpenAPI Specification 的基础。

## 二、什么是OpenAPI

**OpenAPI 规范**（原 Swagger 规范）是一种用于 REST API 的 API 描述格式。OpenAPI 文件允许您描述整个 API，包括：

- 可用端点（`/users`）和每个端点上的操作（`GET /users`、`POST /users`）
- 每个操作的参数输入和输出
- 认证方法
- 联系信息、许可、使用条款和其他信息。

API 规范可以用 YAML 或 JSON 编写。该格式易于学习，对人类和机器都可读。完整的 OpenAPI 规范可在 GitHub 上找到：[OpenAPI 3.0 规范](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.4.md)

## 三、什么是Knife4j

**Knife4j** 是一个基于 Swagger 的增强解决方案，用于生成更美观且功能丰富的 API 文档。

## 四、添加依赖

Maven仓库地址：[Maven Repository: com.github.xiaoymin » knife4j-openapi3-jakarta-spring-boot-starter](https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter)

```xml

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>
```

**注意**：Spring Boot 3 只支持OpenAPI3规范；Knife4j提供的starter已经引用`springdoc-openapi`的jar，开发者需注意避免jar包冲突；JDK版本必须 >= `17`

## 五、编写配置文件

创建`knife4j.yaml`文件

```yml
# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: cn.doooog.[project].controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
```

## 六、编写配置类

创建`SwaggerConfig.java`类

```java
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("RESTful API 文档")
                        .contact(new Contact()
                                 .name("奇记博客")
                                 .email("doooogcn@foxmail.com")
                                 .url("https://soki.me"))
                        .description("项目接口的描述")
                        .version("v1.0.0");
    }
}
```

## 七、常用注解

| 注解名称     | 作用描述              | 主要用法                               | 示例                                                                                  |
| ------------ | --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
| @Tag         | 用于对API操作进行分组 | 在类或方法级别使用，定义API标签        | `@Tag(name = "用户管理", description = "用户相关操作")`                               |
| @Operation   | 描述API操作的基本信息 | 在方法级别使用，描述HTTP方法           | `@Operation(summary = "创建用户", description = "根据输入创建新用户")`                |
| @Parameters  | 描述API操作的多个参数 | 在方法参数前使用，内嵌套@Parameter使用 | `@Parameters({@Parameter(name = "userId", description = "用户ID", required = true)})` |
| @Parameter   | 描述API操作的参数     | 在方法参数前使用，描述参数详情         | `@Parameter(name = "userId", description = "用户ID", required = true)`                |
| @ApiResponse | 定义API的响应信息     | 在方法级别使用，描述响应状态           | `@ApiResponse(responseCode = "200", description = "成功响应")`                        |
| @Schema      | 描述数据模型的结构    | 在DTO类或字段上使用                    | `@Schema(description = "用户信息", required = true)`                                  |
| @RequestBody | 描述请求体内容        | 在方法参数前使用                       | `@RequestBody(description = "用户创建数据", required = true)`                         |
| @Hidden      | 隐藏API或模型         | 在类、方法或字段上使用                 | `@Hidden // 隐藏此API`                                                                |

## 八、访问

最后，访问Knife4j的文档地址：`http://ip:port/doc.html`即可查看文档。

更详细内容请参考官方文档：[快速开始 | Knife4j](https://doc.xiaominfo.com/docs/quick-start)

## 一、什么是Swagger

Swagger 是一套用于设计、构建、文档化和测试 RESTful API 的开源工具集。

Swagger 提供了一种标准化的方式来描述 API 的结构、请求参数、响应格式等信息，使得前后端开发人员能够更高效地协作。

Swagger 是由 SmartBear Software 提供的一套 API 开发工具集，最初是独立的 API 规范，现在已成为 OpenAPI Specification 的基础。

## 二、什么是OpenAPI

**OpenAPI 规范**（原 Swagger 规范）是一种用于 REST API 的 API 描述格式。OpenAPI 文件允许您描述整个 API，包括：

- 可用端点（`/users`）和每个端点上的操作（`GET /users`、`POST /users`）
- 每个操作的参数输入和输出
- 认证方法
- 联系信息、许可、使用条款和其他信息。

## 三、什么是Knife4j

**Knife4j** 是一个基于 Swagger 的增强解决方案，用于生成更美观且功能丰富的 API 文档。

## 四、添加依赖

**注意**：Spring Boot 3 只支持OpenAPI3规范；Knife4j提供的starter已经引用`springdoc-openapi`的jar，开发者需注意避免jar包冲突；JDK版本必须 >= `17`

## 五、编写配置文件

创建`knife4j.yaml`文件

## 六、编写配置类

创建`SwaggerConfig.java`类

## 七、常用注解

## 八、访问

最后，访问Knife4j的文档地址：`http://ip:port/doc.html`即可查看文档。

更详细内容请参考官方文档：[快速开始 | Knife4j](https://doc.xiaominfo.com/docs/quick-start)

最后修改：2025 年 11 月 20 日

👆请简单粗暴地爱我。

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

Spring框架依赖注入

MySQL知识扩展

Day12 - JDBC驱动安装及其简单使用方法

Java常用注解表

Electron的简介

Java各种程序或框架创建流程

JDBC基础模板

Java高级编程

Day2 - 分支、选择与while循环详解

Day14 - elm后端JDBC版商家部分

Swagger文档生成

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

Swagger文档生成

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款