---
title: "10-swagger-knife4j"
created: 2025-12-02
tags:
  - 项目
aliases:
  - swagger-knife4j
---
# swagger/knife4j

在Java开发中，`Swagger` 和 `Knife4j` 都是用于生成和管理API文档的工具，尤其是在Spring
Boot等框架中广泛使用。

### 1. **Swagger**

Swagger 是一种用于描述和文档化 RESTful API 的开源工具集。它主要包括以下几个部分：

- **Swagger UI**：通过生成交互式的Web界面来展示API文档，开发者可以直接通过界面测试API接口。
- **Swagger Editor**：提供一个界面来编写API规范（通常是OpenAPI规范）。
- **Swagger Codegen**：自动生成客户端和服务器端代码。

Swagger 可以通过注解（例如 `@Api`, `@ApiOperation`, `@ApiParam` 等）来生成API的文档。Spring
Boot 项目中通常会集成 `springfox-swagger2` 或者 `springdoc-openapi` 来实现Swagger功能。

#### 常见使用步骤（Spring Boot 集成 Swagger）：

1. **依赖**：

```xml
   <!-- Springfox Swagger 2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   ```
2. **配置**： 创建一个 Swagger 配置类：

```java
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example"))
               .paths(PathSelectors.any())
               .build();
       }
   }
   ```
3. **访问文档**： 启动项目后，可以访问 `http://localhost:8080/swagger-ui.html` 来查看和测试API接口。

### 2. **Knife4j**

Knife4j 是一个在 Swagger 的基础上进行扩展的工具，旨在提供更强大的功能和更好的用户体验。它为 Swagger 提供了更加美观和易用的用户界面，并且提供了一些增强功能。

- **UI界面**：比默认的Swagger UI更为现代和漂亮，支持分组管理API、接口文档排序、搜索等功能。
- **支持动态接口文档**：允许通过动态刷新和在线调试接口，支持多种格式的文档展示。

#### 常见使用步骤（Spring Boot 集成 Knife4j）：

1. **依赖**：

```xml
   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-springboot-starter</artifactId>
       <version>2.0.7</version>
   </dependency>
   ```
2. **配置**： 一般来说，集成 Knife4j 后，它会自动使用 Swagger 的配置。如果需要自定义配置，可以在 `SwaggerConfig` 类中添加：

```java
   @Configuration
   public class Knife4jConfig {
       @Bean
       public Docket docket() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.example"))
                   .paths(PathSelectors.any())
                   .build();
       }

       private ApiInfo apiInfo() {
           return new ApiInfo(
               "API文档",
               "API接口文档",
               "1.0",
               "http://www.example.com",
               new Contact("开发者", "http://www.example.com", "developer@example.com"),
               "许可证",
               "许可证链接",
               Collections.emptyList());
       }
   }
   ```
3. **访问文档**： 使用 Knife4j 后，接口文档可以通过 `http://localhost:8080/doc.html` 访问，提供更加美观的界面和更丰富的交互功能。

### 总结：

- **Swagger**：一个强大的工具集，用于描述、生成和展示API文档。
- **Knife4j**：基于 Swagger 的扩展，提供了更丰富的功能和更好的用户体验。

通常，如果你在 Spring Boot 项目中使用 Swagger 文档，集成 Knife4j 是一个不错的选择，能够提升开发效率和文档的易用性。

---

**项目分区导航**：⬅️ [[09-接口文档|09-接口文档]] | 10-swagger-knife4j | ➡️ [[11-推荐用户|11-推荐用户]]