Swagger的原理及应用详解(七)

本系列文章简介:

        在当今快速发展的软件开发领域,特别是随着微服务架构和前后端分离开发模式的普及,API(Application Programming Interface,应用程序编程接口)的设计与管理变得愈发重要。一个清晰、准确且易于理解的API文档不仅能够提升开发效率,还能促进前后端开发者之间的有效沟通,减少因文档不一致或缺失导致的错误和返工。然而,传统的手写API文档方式往往存在更新不及时、易出错、难以维护等问题。

        正是在这样的背景下,Swagger应运而生,它作为一款强大的API文档自动生成工具,极大地简化了API文档的编写和管理工作。Swagger通过扫描代码中的注解,自动生成详细的API文档,并支持在线测试,使得开发者可以直观地看到API的请求参数、响应结果以及可能的错误码等信息。

        本系列文章旨在深入解析Swagger的原理核心组件应用场景以及搭建配置等关键内容,帮助大家全面了解并高效利用Swagger这一工具。我们将从Swagger的概述开始,逐步深入到其工作原理、核心组件的详细介绍,以及在不同开发场景下的应用实践。同时,我们还将探讨Swagger在前后端分离开发、API文档管理、API测试与调试等方面的实际应用,以及如何解决在使用过程中遇到的一些常见问题。

        通过本系列文章的学习,大家将能够掌握Swagger的基本使用方法,理解其背后的技术原理,并能够根据项目的实际需求灵活运用Swagger来提升API文档的质量和开发效率。此外,本文还将提供一些学习资源和最佳实践,帮助大家进一步提升在API设计和文档管理方面的能力。

        总之,Swagger作为一款优秀的API文档自动生成工具,在软件开发领域具有广泛的应用前景和重要的实用价值。希望通过本系列文章的详细解析和介绍,能够为大家在API文档的编写和管理工作中提供有力的支持和帮助。

        欢迎大家订阅《Java技术栈高级攻略》专栏(PS:近期会涨价),一起学习,一起涨分!

目录

一、引言

二、Swagger的搭建与配置

2.1 环境准备

2.1.1 Maven或Gradle项目搭建

2.1.2 设置API的标题、版本、描述等信息

2.2 使用Swagger注解

2.2.1 在Controller和实体类上使用Swagger注解

2.2.2 编写API文档说明

三、Swagger的进阶使用

3.1 自定义Swagger UI

3.2 Swagger与Spring Boot集成

3.3 Swagger与其他框架的集成

四、常见问题与解决方案

4.1 Swagger UI无法访问

4.2 生成的API文档不准确

4.3 Swagger性能优化

五、总结与展望

六、结语


一、引言

        Swagger(OpenAPI Specification)是一个功能强大的框架和规范,它通过自动化生成文档、提供详细的API描述以及支持调用和可视化等功能,极大地简化了API的设计、构建、使用和理解过程。无论是在企业内部还是跨企业的API合作中,Swagger都发挥着重要的作用。

        本文将跟随《Swagger的原理及应用详解(六)》的进度,继续介绍Swagger。希望通过本系列文章的学习,您将能够更好地理解Swagger的内部工作原理,掌握Swagger的使用技巧,以及通过合理的设计完成最佳实践,充分发挥优化Swagger的潜力,为系统的高效运行提供有力保障。

二、Swagger的搭建与配置

2.1 环境准备

2.1.1 Maven或Gradle项目搭建

Swagger的搭建与配置在Maven或Gradle项目中是一个相对直接的过程,主要涉及引入依赖、配置Swagger以及(可选地)在Controller中使用Swagger注解。以下是详细的步骤说明:

Maven项目搭建Swagger

1. 引入Swagger依赖

在Maven项目的pom.xml文件中,添加Swagger的依赖项。为了保持兼容性,建议使用经过验证的稳定版本,如2.9.2

<dependencies> <!-- Swagger2核心包 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- Swagger-UI --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> </dependencies>

 

2. 配置Swagger

创建一个配置类,用于配置Swagger的详细信息,如API信息、扫描的包等。在该类上添加@Configuration@EnableSwagger2注解。

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描的包 .paths(PathSelectors.any()) // 扫描所有路径 .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API Documentation") .description("Documentation for my API") .version("1.0") .build(); } }

3. (可选)在Controller中使用Swagger注解

在Controller类和方法上使用Swagger的注解来丰富API文档的信息。

import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController @Api(value = "测试接口Controller", description = "测试接口说明") public class TestController { @GetMapping("/test") @ApiOperation(value = "测试接口", notes = "这是一个测试接口") public String test() { return "Hello, Swagger!"; } }

4. 访问Swagger UI

启动Spring Boot应用后,通过浏览器访问http://localhost:8080/swagger-ui.html(端口号可能因配置而异)来查看Swagger UI界面。

Gradle项目搭建Swagger

1. 引入Swagger依赖

在Gradle项目的build.gradle文件中,添加Swagger的依赖项。

dependencies { implementation 'io.springfox:springfox-swagger2:2.9.2' implementation 'io.springfox:springfox-swagger-ui:2.9.2' }

2. 配置Swagger

与Maven项目类似,创建一个配置类来配置Swagger。

// 配置类代码与Maven项目中的SwaggerConfig类相同

 

3. (可选)在Controller中使用Swagger注解

与Maven项目相同,在Controller中使用Swagger注解来丰富API文档的信息。

4. 访问Swagger UI

启动Spring Boot应用后,通过浏览器访问http://localhost:8080/swagger-ui.html(端口号可能因配置而异)来查看Swagger UI界面。

总结

无论是在Maven还是Gradle项目中搭建Swagger,主要步骤都包括引入依赖、配置Swagger以及(可选地)在Controller中使用Swagger注解。通过这些步骤,可以方便地生成和查看RESTful API的文档,并提供接口测试的功能。


2.1.2 设置API的标题、版本、描述等信息

在Swagger中,你可以通过配置Swagger的Docket Bean来设置API的标题、版本、描述等信息。这些设置通常是在你的Swagger配置类中完成的,该类通过@Configuration@EnableSwagger2注解来启用Swagger。

以下是一个示例,展示了如何设置API的标题、版本和描述等信息:

import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.Configuration;  
import springfox.documentation.builders.ApiInfoBuilder;  
import springfox.documentation.builders.PathSelectors;  
import springfox.documentation.builders.RequestHandlerSelectors;  
import springfox.documentation.spi.DocumentationType;  
import springfox.documentation.spring.web.plugins.Docket;  
import springfox.documentation.swagger2.annotations.EnableSwagger2;  @Configuration  
@EnableSwagger2  
public class SwaggerConfig {  @Bean  public Docket api() {  return new Docket(DocumentationType.SWAGGER_2)  .select()  // 指定扫描的包  .apis(RequestHandlerSelectors.basePackage("com.yourcompany.project.controller"))  // 扫描所有路径  .paths(PathSelectors.any())  .build()  // 设置API信息  .apiInfo(apiInfo());  }  private ApiInfo apiInfo() {  // 返回一个ApiInfo实例,用于定制API信息  return new ApiInfoBuilder()  // API标题  .title("Your API Title")  // API描述  .description("A detailed description of your API")  // 版本号  .version("1.0.0")  // 许可信息(可选)  .license("Apache 2.0")  .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")  .build();  }  
}

 

在这个例子中,apiInfo()方法创建了一个ApiInfo实例,该实例包含了API的标题、描述、版本以及许可信息(如果适用)。这些信息会被Swagger UI用来显示API的概览信息。

  • title:API的标题,显示在Swagger UI的顶部。
  • description:API的详细描述,通常包含API的用途、功能等信息。
  • version:API的版本号,有助于区分不同版本的API。
  • licenselicenseUrl:API的许可信息和许可URL(可选),这些信息对于开源项目尤其有用。

配置完成后,当你访问Swagger UI时(通常是http://localhost:8080/swagger-ui.html,端口号可能因你的配置而异),你就可以在页面的顶部看到这些API信息了。

2.2 使用Swagger注解

2.2.1 在Controller和实体类上使用Swagger注解

在Swagger中,使用注解来丰富API文档的信息是一种非常直接和有效的方法。Swagger提供了多种注解,可以在Controller(控制器)和实体类(Model)上使用,以提供更详细的API描述、参数说明、响应信息等。以下是一些常用的Swagger注解及其在Controller和实体类上的使用示例。

在Controller上使用Swagger注解

  1. @Api:用于标记当前类是一个Swagger资源(API),并可以指定一些元数据信息,如tags。
import io.swagger.annotations.Api;  
import io.swagger.annotations.ApiOperation;  @RestController  
@RequestMapping("/api/v1/users")  
@Api(tags = "用户管理")  
public class UserController {  // ...  
}

        2. @ApiOperation:用于标记一个方法(通常是Controller中的一个方法)的操作,可以指定操作的描述、HTTP方法、响应类型等信息。

 

import io.swagger.annotations.ApiOperation;  @GetMapping("/{id}")  
@ApiOperation(value = "根据ID获取用户信息", notes = "返回指定ID的用户详细信息")  
public ResponseEntity<User> getUserById(@PathVariable Long id) {  // ...  
}

        3. @ApiParam:用于标记方法参数,可以指定参数的名称、描述等信息。

import io.swagger.annotations.ApiParam;  @PostMapping  
@ApiOperation(value = "创建新用户")  
public ResponseEntity<User> createUser(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {  // ...  
}

        4. @ApiResponses 和 @ApiResponse:用于描述方法可能的响应。@ApiResponses 可以包含多个 @ApiResponse

import io.swagger.annotations.ApiResponses;  
import io.swagger.annotations.ApiResponse;  @PostMapping  
@ApiOperation(value = "更新用户信息")  
@ApiResponses({  @ApiResponse(code = 200, message = "更新成功"),  @ApiResponse(code = 404, message = "用户未找到")  
})  
public ResponseEntity<Void> updateUser(@RequestBody User user) {  // ...  
}

 

在实体类上使用Swagger注解

虽然Swagger的注解主要用于Controller层,但实体类(Model)上的某些Java标准注解(如@JsonProperty@JsonIgnore等)也会间接影响Swagger生成的文档。不过,Swagger也提供了一些特定的注解来丰富Model的描述。

  1. @ApiModel:用于描述一个Model的信息(一般用于类上),如描述、名称等。
import io.swagger.annotations.ApiModel;  @ApiModel(description = "用户信息")  
public class User {  // ...  
}

        2. @ApiModelProperty:用于描述Model的字段(属性)的详细信息,如名称、描述、是否必需等。

import io.swagger.annotations.ApiModelProperty;  public class User {  @ApiModelProperty(value = "用户ID", example = "12345")  private Long id;  @ApiModelProperty(value = "用户名", required = true)  private String username;  // ...  
}

 

请注意,Swagger的注解(如@Api@ApiOperation等)和Springfox(一个常用的Swagger集成库)的注解(如@ApiInfo)是不同的。在上面的示例中,我主要使用了Swagger的注解,因为它们是直接由Swagger项目提供的,并且与Swagger UI紧密集成。然而,在Spring Boot项目中,你通常会通过Springfox(现在可能被称为Springdoc OpenAPI,Springfox的替代品)来集成Swagger,但注解的使用方式大致相同。

2.2.2 编写API文档说明

Swagger的搭建与配置过程中,编写API文档说明是一个核心环节。以下是一个清晰的案例指南:

 编写Controller和注解

在你的Controller中,你需要使用Swagger提供的注解来描述API的方法、参数、响应等信息。这些注解包括但不限于:

  • @Api:用于Controller类上,描述该类的作用。
  • @ApiOperation:用于方法上,描述该方法的作用。
  • @ApiImplicitParams@ApiImplicitParam:用于描述方法的参数。
  • @ApiResponses@ApiResponse:用于描述方法的响应。
  • @ApiModel@ApiModelProperty:用于描述返回对象的模型。
import io.swagger.annotations.Api;  
import io.swagger.annotations.ApiOperation;  
import io.swagger.annotations.ApiImplicitParam;  
import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RequestParam;  
import org.springframework.web.bind.annotation.RestController;  @RestController  
@Api(tags = "UserController")  
public class UserController {  @GetMapping("/user")  @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")  @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long")  public User getUser(@RequestParam Long userId) {  // 方法实现  return new User();  }  
}

访问Swagger UI

配置完成后,你可以通过访问Swagger UI来查看你的API文档。通常,Swagger UI的访问地址是http://localhost:8080/swagger-ui.html(端口号可能因你的配置而异)。在Swagger UI页面上,你可以看到所有被Swagger扫描并生成的API文档,包括API的标题、描述、版本信息,以及每个API的方法、参数、响应等详细信息。

总结

编写Swagger API文档说明主要涉及到引入Swagger依赖、配置Swagger、编写Controller和注解以及访问Swagger UI等步骤。通过这些步骤,你可以为你的Web服务生成详细、易读的API文档,方便前后端开发人员之间的沟通和协作。

三、Swagger的进阶使用

3.1 自定义Swagger UI

       详见《Swagger的原理及应用详解(八)

3.2 Swagger与Spring Boot集成

       详见《Swagger的原理及应用详解(九)

3.3 Swagger与其他框架的集成

       详见《Swagger的原理及应用详解(十)

四、常见问题与解决方案

4.1 Swagger UI无法访问

        详见《Swagger的原理及应用详解(十一)

4.2 生成的API文档不准确

        详见《Swagger的原理及应用详解(十一)

4.3 Swagger性能优化

        详见《Swagger的原理及应用详解(十二)

五、总结与展望

        详见《Swagger的原理及应用详解(十二)

六、结语

        文章至此,已接近尾声!希望此文能够对大家有所启发和帮助。同时,感谢大家的耐心阅读和对本文档的信任。在未来的技术学习和工作中,期待与各位大佬共同进步,共同探索新的技术前沿。最后,再次感谢各位的支持和关注。您的支持是作者创作的最大动力,如果您觉得这篇文章对您有所帮助,请分享给身边的朋友和同事!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/bicheng/40946.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

将 WSL(Windows Subsystem for Linux)移动到另一个盘上

方法一&#xff1a;通过 wsl --export 和 wsl --import 命令 导出当前的 WSL 分发版&#xff1a; 首先&#xff0c;您需要导出当前运行的 WSL 分发版。假设您的分发版名称为 Ubuntu-20.04&#xff0c;执行以下命令&#xff1a; wsl --export Ubuntu-20.04 D:\WSL\Ubuntu-20.04.…

护眼落地灯哪个牌子好?盘点五款必入不踩雷的护眼大路灯

护眼落地灯哪个牌子好&#xff1f;在这个快节奏的时代&#xff0c;护眼落地灯已经从一种高端选择转变为日常用眼生活中的必须品。不论是提升普通照明&#xff0c;还是针对孩子学习是改善光线质量环境&#xff0c;一款优秀的护眼落地灯都能成为我们生活中的照明神器。怎么选择一…

Java实现电子围栏的小例子

主要需求是实现一个电子围栏判断的小例子其中包括前端和后端的demo代码 引入对应的依赖库 <!--jts库通常用于几何计算和表示地理空间数据--> <dependency><groupId>org.locationtech.jts</groupId><artifactId>jts-core</artifactId><…

Python中定位一个序列中特点值出现的位置,比如 [0,0,0,1,1,0,0,]中1的位置

已知 Python中计算一个序列中特点值出现的数量&#xff0c;比如 [0,0,0,1,1,0,0,]中1的数量 如何定位位置呢 要找到列表 [0, 0, 0, 1, 1, 0, 0] 中 1 出现的位置&#xff08;索引&#xff09;&#xff0c;可以使用 Python 的列表推导式或者循环。以下是几种方法&#xff1a; …

在 VS Code 中自动化 Xcode 项目编译和调试

在 VS Code 中自动化 Xcode 项目编译和调试 在日常的开发工作中&#xff0c;Xcode 是 macOS、iOS、watchOS 和 tvOS 应用程序开发的主要工具。为了提高工作效率&#xff0c;许多开发者选择在 Visual Studio Code (VS Code) 中编辑代码&#xff0c;并希望能够直接从 VS Code 启…

无线传感器网络(物联网通信技术)期末考试2024年真题

目录 WSN期末复习资料 第一章&#xff1a;概述 第二章MAC协议 第三章路由协议 第四章时间同步技术 第五章定位技术 第六章安全技术 第七章拓扑控制 补充TPSN、HRTS公式推导 2024年期末考试考点 一、简述 二、考试真题回忆 WSN期末复习资料 第一章&#xff1a;概述 …

蓝桥杯开发板STM32G431RBT6高阶HAL库学习FreeRtos——新建工程

一、介绍 ​ 蓝桥杯嵌入式使用的单片机是STM32G431RBT6&#xff0c;内核ARM Cortex - M4&#xff0c;MCUFPU&#xff0c;170MHz/213DMIPS&#xff0c;高达128KB Flash&#xff0c;32KB SRAM&#xff0c;其余的外设就不多介绍了&#xff0c;参照数据芯片数据手册 ​ CT117E-M4…

JavaScript——while类型

目录 任务描述 相关知识 while类型 编程要求 任务描述 质数的定义如下&#xff1a;大于1的自然数&#xff0c;且除了1和本身外没有别的因数。如2、3、5、7。 本关任务&#xff1a;利用循环结构求质数的和。 相关知识 在选择结构中&#xff0c;条件会被测试一次&#xff…

【matlab】信号分解/故障诊断——智能优化算法优化VMD

目录 引言 应用领域 VMD代码实现 智能优化算法优化VMD 引言 VMD&#xff08;变分模态分解&#xff09;是一种新的非线性自适应信号分解方法&#xff0c;它通过变分原理将复杂信号分解为若干个具有不同频率中心和带宽的本征模态函数&#xff08;Intrinsic Mode Functions, …

74HC165芯片验证

目录 0x01 74HC165芯片介绍0x02 编程实现 0x01 74HC165芯片介绍 74HC165的引脚定义如下&#xff0c;长这个样子 ABCDEFGH是它的八个输入引脚&#xff0c;例如你可以将它连接按键&#xff0c;让它来读取8个按键值。也可以将他级联其它的74165&#xff0c;无需增加单片机GPIO引…

代码动态编译

背景 开发环境下新加代码、改代码时要重启后生效&#xff08;耗时间&#xff09;&#xff1b;需求:不用重启且支持springboot 、spring、MyBatis。 实现 下地地址&#xff1a;https://github.com/JetBrains/JetBrainsRuntime/releases 1.根据系统类型下载压缩包 2.解压后配…

esp32-nvs使用

_____ 使用步骤 1, 初始化 nvs 分区 2, 打开 namespaec 3, 读取或写入键值 如果是 string 或数组类型,先读长度 -- 获取单个数据的值 1, 初始化分区 // Initialize NVSesp_err_t err = nvs_flash_init();if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW…

Ubuntu 22.04.4 LTS 安装配置 MySQL Community Server 8.0.37 LTS

1 安装mysql-server sudo apt update sudo apt-get install mysql-server 2 启动mysql服务 sudo systemctl restart mysql.service sudo systemctl enable mysql.service #查看服务 sudo systemctl status mysql.service 3 修改mysql root密码 #默认密码为空 sudo mysql …

SQL 注入联合查询之为什么要 and 1=2

在 SQL 注入联合查询中&#xff0c;将 id 先置为假&#xff08;如 id-1 或其他使查询结果为空的条件&#xff09;&#xff0c;通常是为了让前面的查询语句查询不到结果&#xff0c;从而使联合查询中后面的语句结果能够显示在回显位上

【串口通信】之TTL电平

1. 什么是串口 串口,全称为串行通信端口,是一种计算机硬件接口,用于实现数据的串行传输。与并行通信不同,串口通信一次只传输一个比特,数据通过串行线按顺序传输。串口通信在嵌入式系统、工业控制、计算机与外围设备通信等领域非常常见 2. 什么是串口通信 串口通信是指通过…

设计模式实现思路介绍

设计模式是在软件工程中用于解决特定问题的典型解决方案。它们是在多年的软件开发实践中总结出来的&#xff0c;并且因其重用性、通用性和高效性而被广泛接受。设计模式通常被分为三种主要类型&#xff1a;创建型、结构型和行为型。 创建型设计模式 创建型设计模式专注于如何创…

在线签约如何选择?2024年10款顶级app大比拼

支持电子合同签约的10大app&#xff1a;e签宝、上上签、DocuSign、契约锁、Adobe Sign、法大大、SignNow、安心签、HelloSign、PandaDoc。 无论是企业之间的交易还是个人服务合同&#xff0c;线上电子合同签约提供了一种便捷、高效且安全的方式来处理法律文档。本文将介绍几款优…

RISC-V在当前计算架构中的地位

基于上个视频&#xff0c;我们对RISC-V已经有了一定的了解。这款开源的新生代指令集架构与传统商业指令集架构有很大区别&#xff0c;比如当下最热门的Intel的x86和ARM。这主要体现在以下几个方面&#xff1a; 开放性&#xff0c;任何人与机构都可以具体的应用需求调整和优化R…

【Python实战因果推断】20_线性回归的不合理效果10

目录 Neutral Controls Noise Inducing Control Feature Selection: A Bias-Variance Trade-Off Neutral Controls 现在&#xff0c;您可能已经对回归如何调整混杂变量有了一定的了解。如果您想知道干预 T 对 Y 的影响&#xff0c;同时调整混杂变量 X&#xff0c;您所要做的…

springboot项目怎么样排除自带tomcat容器使用宝蓝德?

前言&#xff1a; 由于Spring Boot 1.x和2.x不兼容&#xff0c;BES提供了对应的Spring Boot Starter版本。 bes‑lite‑spring‑boot‑1.x‑starter.jar&#xff0c;适用于Spring Boot 1.x的版本。 bes‑lite‑spring‑boot‑2.x‑starter…