Swagger:swagger和knife4j

Shaw0xyz

1. 简介

在现代软件开发中，API的设计与文档化是至关重要的环节。Swagger和Knife4j是两款广泛使用的API文档生成工具。本文将详细介绍Swagger和Knife4j的基本概念、使用方法及其在实际开发中的应用。

1.1 Swagger简介

Swagger是一个用于生成、描述、调用和可视化RESTful风格Web服务的开源工具。它通过注释或配置文件自动生成API文档，使开发者可以轻松地与API进行交互和测试。

1.2 Knife4j简介

Knife4j是对Swagger的增强版，专注于为Swagger的文档提供更好的用户体验。它增加了更多功能和优化，适用于国内开发者，更符合国人的使用习惯。

2. 安装与配置

在开始使用Swagger和Knife4j之前，我们需要进行安装和配置。以下步骤将指导您完成这一过程。

2.1 安装Swagger

(1) 添加Swagger依赖

在Spring Boot项目的`pom.xml`文件中添加以下依赖：

1. <dependency>
   
2.     <groupId>io.springfox</groupId>
   
3.     <artifactId>springfox-swagger2</artifactId>
   
4.     <version>2.9.2</version>
   
5. </dependency>
   
6. <dependency>
   
7.     <groupId>io.springfox</groupId>
   
8.     <artifactId>springfox-swagger-ui</artifactId>
   
9.     <version>2.9.2</version>
   
10. </dependency>

复制代码

(2) 配置Swagger

在项目的配置文件中添加Swagger的配置类：

1. import org.springframework.context.annotation.Bean;
   
2. import org.springframework.context.annotation.Configuration;
   
3. import springfox.documentation.builders.ApiInfoBuilder;
   
4. import springfox.documentation.builders.PathSelectors;
   
5. import springfox.documentation.builders.RequestHandlerSelectors;
   
6. import springfox.documentation.spi.DocumentationType;
   
7. import springfox.documentation.spring.web.plugins.Docket;
   
8. import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
9. 
   
10. @Configuration
    
11. @EnableSwagger2
    
12. public class SwaggerConfig {
    
13.    
    
14.     @Bean
    
15.     public Docket api() {
    
16.         return new Docket(DocumentationType.SWAGGER_2)
    
17.                 .select()
    
18.                 .apis(RequestHandlerSelectors.basePackage("com.example"))
    
19.                 .paths(PathSelectors.any())
    
20.                 .build()
    
21.                 .apiInfo(apiInfo());
    
22.     }
    
23. 
    
24.     private ApiInfo apiInfo() {
    
25.         return new ApiInfoBuilder()
    
26.                 .title("API文档")
    
27.                 .description("API文档描述")
    
28.                 .version("1.0")
    
29.                 .build();
    
30.     }
    
31. }

复制代码

2.2 安装Knife4j

在安装Swagger的基础上，添加Knife4j的依赖和配置。

(1) 添加Knife4j依赖

在`pom.xml`文件中添加以下依赖：

1. <dependency>
   
2.     <groupId>com.github.xiaoymin</groupId>
   
3.     <artifactId>knife4j-spring-boot-starter</artifactId>
   
4.     <version>2.0.9</version>
   
5. </dependency>

复制代码

(2) 配置Knife4j

在Swagger配置类中，启用Knife4j：

1. import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
   
2. 
   
3. @Configuration
   
4. @EnableSwagger2
   
5. @EnableKnife4j
   
6. public class SwaggerConfig {
   
7.     // 配置内容同Swagger配置
   
8. }

复制代码

3. 使用Swagger和Knife4j

配置完成后，可以通过浏览器访问Swagger和Knife4j生成的API文档。

3.1 访问Swagger文档

启动Spring Boot项目后，打开浏览器并访问以下地址：

1. http://localhost:8080/swagger-ui.html

复制代码

在该页面中，可以查看和测试所有API接口。

3.2 访问Knife4j文档

在Swagger文档的基础上，Knife4j提供了更友好的界面和更多功能。可以通过以下地址访问：

1. http://localhost:8080/doc.html

复制代码

4. 实践案例

为了更好地理解Swagger和Knife4j的使用，以下是一个实际的Spring Boot项目案例。

4.1 创建一个简单的RESTful API

(1) 创建一个控制器类：

1. import org.springframework.web.bind.annotation.GetMapping;
   
2. import org.springframework.web.bind.annotation.RequestMapping;
   
3. import org.springframework.web.bind.annotation.RestController;
   
4. 
   
5. @RestController
   
6. @RequestMapping("/api")
   
7. public class ApiController {
   
8.    
   
9.     @GetMapping("/hello")
   
10.     public String hello() {
    
11.         return "Hello, World!";
    
12.     }
    
13. }

复制代码

(2) 访问API文档

启动项目后，访问`http://localhost:8080/doc.html`，可以看到`/api/hello`接口的详细信息。

5. 总结

Swagger和Knife4j是两款强大的API文档生成工具，可以极大地提升API文档的编写效率和用户体验。通过本文的介绍，您应该已经掌握了它们的基本使用方法及其在实际项目中的应用。希望本文对您有所帮助，如果有任何疑问或建议，欢迎交流讨论。







/ 荔枝学姐de课后专栏 /

Hi！这里是荔枝学姐~

欢迎来到我的课后专栏

自然语言学渣 NLP摆烂姐

热衷于技术写作 IT边角料

AIGC & Coding & linux ...

~互撩~ TG: @Shaw_0xyz