当前位置：首页 > 科技 > 软件

前后端分离项目必备——自动生成API文档神器Swagger

来源：责编：时间：2023-09-21 20:48:13 193观看

导读Swagger的故事随着Web服务的发展，RESTful风格的API越来越受到开发者的青睐，因为它简单且符合Web的本质。Spring框架也不落人后，提供了一个名为Spring MVC的模块，用于支持RESTful API的开发。Spring MVC是一个基于注解的We

Swagger的故事

随着Web服务的发展，RESTful风格的API越来越受到开发者的青睐，因为它简单且符合Web的本质。Spring框架也不落人后，提供了一个名为Spring MVC的模块，用于支持RESTful API的开发。Spring MVC是一个基于注解的Web框架，让开发者可以使用简洁且优雅的方式定义和实现API。

然而Spring MVC并没有提供一个方便且标准的方式来描述和文档化API，这给API的管理和维护带来了一定的困难。为了解决这个问题，一个名为Swagger的项目诞生了。Swagger是由Tony Tam在2010年创建的一个开源项目，旨在为RESTful API提供一个规范且完整的框架4。Tony Tam是一个资深的Java开发者，他在使用Spring MVC开发API时感受到了它的优点和缺点，所以他决定创建一个可以与Spring MVC无缝集成的工具，来帮助开发者更好地设计、描述、调用和可视化API。

Swagger项目很快就得到了开源社区和业界的认可和支持，成为了最流行的API开发工具之一。Swagger项目也不断地演进和完善，涵盖了各种语言和框架，如Python, Ruby, Node.js, Django, Rails等。Swagger项目也不断地与其他标准和工具集成，如OpenAPI Specification, Postman, Apigee等。

Swagger的作用

Swagger的主要作用是为RESTful风格的Web服务提供一个标准且完整的框架，包括以下几个方面：

生成：Swagger可以根据代码或者手动编写的规范文件，自动生成API文档，包括请求参数、响应结果、错误码等信息。这样可以节省编写文档的时间，也可以保证文档和代码的一致性。
描述：Swagger可以使用一种结构化的语言（如YAML或JSON）来描述API的元数据，如接口名称、路径、方法、参数类型、返回值类型等。这样可以方便地对API进行管理和维护，也可以方便地进行版本控制和协作开发。
调用：Swagger可以提供一个可视化的用户界面（如Swagger UI），让用户可以直接在浏览器中对API进行测试和调试，而不需要使用其他的工具（如Postman或curl）。这样可以提高开发效率，也可以方便地验证API的功能和性能。
可视化：Swagger可以提供一个图形化的用户界面（如Swagger Editor），让用户可以以图形化的方式编辑和查看API规范文件，而不需要关心语法细节。这样可以提高用户体验，也可以方便地进行错误检查和修正。

Swagger的好处

Swagger作为一个流行且成熟的API开发工具，它有以下几个好处：

标准化：Swagger遵循OpenAPI规范，这是一个业界公认且广泛使用的RESTful API描述标准。使用Swagger可以保证API的兼容性和互操作性，也可以方便地与其他遵循OpenAPI规范的工具集成。
灵活性：Swagger支持多种编程语言和框架，如Java, Python, Ruby, Node.js, Spring, Django, Rails等。使用Swagger可以根据不同的需求和场景选择合适的技术栈，也可以轻松地迁移和重构代码。
易用性：Swagger提供了丰富且易用的工具和用户界面，让用户可以快速地创建、修改、查看和测试API。使用Swagger可以降低API开发的门槛和难度，也可以提高API开发的质量和效率。

Swagger项目现在已经成为了一个庞大且活跃的生态系统，包括以下几个部分：

Swagger Core：提供了一系列的库和工具，用于生成、解析、验证和转换Swagger规范文件。
Swagger UI：提供了一个可视化的用户界面，用于展示、测试和调试API。
Swagger Editor：提供了一个图形化的用户界面，用于编辑和查看Swagger规范文件。
Swagger Codegen：提供了一个代码生成器，用于根据Swagger规范文件生成客户端和服务端代码。
Swagger Inspector：提供了一个在线工具，用于检查、测试和分析API。
Swagger Hub：提供了一个在线平台，用于协作、管理和发布API。

Springboot使用Swagger3生成API文档

步骤说明

在pom.xml文件中添加springdoc-openapi-ui依赖，这是一个支持OAS 3.0的Swagger UI库，它可以自动集成到Spring Boot应用中，并提供一个可视化的用户界面来展示、测试和调试API。
在配置类中添加@OpenAPIDefinition注解，并定义一些API的基本信息，如标题、描述、版本、联系人等。
在控制器类中添加@Tag注解，并定义一些API的分组信息，如名称、描述等。
在方法上添加@Operation注解，并定义一些API的操作信息，如摘要、描述、响应等。
在参数上添加@Parameter注解，并定义一些API的参数信息，如名称、描述、是否必填、示例等。
在模型类上添加@Schema注解，并定义一些API的模型信息，如名称、描述、属性等。

注意：

对于2.x.x版本，访问地址为：http://localhost:8080/{context-path}/swagger-ui.html
对于3.x.x版本，访问地址为：http://localhost:8080/{context-path}/swagger-ui/index.html
其中，localhost是你的本地主机名，8080是你的项目端口号，{context-path}是你的项目上下文路径。你需要根据你的实际情况来替换这些参数。
例如，如果你的项目端口号是8081，上下文路径是demo，Swagger版本是3.0.0，那么你可以访问以下地址来查看Swagger UI界面：
http://localhost:8081/demo/swagger-ui/index.html

pom.xml文件

<dependencies>    <!-- Spring Boot Starter -->    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-web</artifactId>    </dependency>    <!-- springdoc-openapi-ui -->    <dependency>        <groupId>org.springdoc</groupId>        <artifactId>springdoc-openapi-ui</artifactId>        <version>1.5.12</version>    </dependency></dependencies>

配置类

// 配置类@Configuration@OpenAPIDefinition(        info = @Info(                title = "Swagger3示例API",                description = "这是一个使用Swagger3来开发Spring Boot应用中的API的示例",                version = "1.0",                contact = @Contact(                        name = "张三",                        email = "zhangsan@example.com",                        url = "1"                )        ))public class SwaggerConfig {}

控制器类

// 控制器类@RestController@RequestMapping("/user")@Tag(name = "用户管理API", description = "提供用户相关的操作")public class UserController {    @GetMapping("/{id}")    @Operation(summary = "根据ID查询用户信息", description = "返回用户实体对象")    @ApiResponse(responseCode = "200", description = "查询成功")    @ApiResponse(responseCode = "404", description = "用户不存在")    public User getUserById(@PathVariable("id") @Parameter(description = "用户ID", required = true, example = "1") Long id) {        // 模拟查询数据库        User user = new User();        user.setId(id);        user.setName("张三");        user.setAge(18);        return user;    }    @PostMapping("/")    @Operation(summary = "添加用户信息", description = "返回添加结果")    @ApiResponse(responseCode = "200", description = "添加成功")    @ApiResponse(responseCode = "400", description = "参数错误")    public String addUser(@RequestBody @Parameter(description = "用户实体对象", required = true) User user) {        // 模拟插入数据库        return "添加成功";    }}

用户实体类

// 用户实体类@Schema(name = "用户实体类", description = "用户的基本信息")public class User {    @Schema(description = "用户ID")    private Long id;    @Schema(description = "用户姓名")    private String name;    @Schema(description = "用户年龄")    private Integer age;    // 省略getter和setter方法}

Swagger注解总结：

Swagger注解有以下几种类型：

类级别的注解：用于标识一个类是Swagger的资源，可以设置一些全局的属性，如tags、value等。常用的类级别的注解有@Api。
方法级别的注解：用于标识一个方法是一个http请求的操作，可以设置一些操作相关的属性，如value、notes、response等。常用的方法级别的注解有@ApiOperation、@ApiResponses、@ApiResponse等。
参数级别的注解：用于标识一个方法的参数或者一个字段是API的参数，可以设置一些参数相关的属性，如value、required、example等。常用的参数级别的注解有@ApiParam、@ApiImplicitParam等。
模型级别的注解：用于标识一个类是API的模型，可以设置一些模型相关的属性，如value、description等。常用的模型级别的注解有@ApiModel、@ApiModelProperty等。
忽略级别的注解：用于标识一个类或者方法被忽略，不显示在Swagger文档上。常用的忽略级别的注解有@ApiIgnore。

下面是一个对Swagger常用注解的总结表格：

本文链接：http://www.28at.com/showinfo-26-10899-0.html前后端分离项目必备——自动生成API文档神器Swagger

声明：本网页内容旨在传播知识，若有侵权等问题请及时与本网联系，我们将在第一时间删除处理。邮件：2376512515@qq.com

上一篇：深入浅出：分布式、CAP 和 BASE 理论

下一篇： JavaScript 终于原生支持数组分组了！

标签：

热门焦点

容量越大越不坏？24万块硬盘故障率报告公布这些产品零故障

8月5日消息，云存储服务商Backblaze发布了最新的硬盘故障率报告，年故障率有所上升。Backblaze发布的硬盘季度统计数据，其中包括故障率等重要方面。这些结
跑分安卓第一！Redmi K60至尊版8月发布！卢伟冰：目标年度性能之王

8月5日消息，Redmi K60至尊版将于8月发布，在此前举行的战略发布会上，官方该机将搭载搭载天玑9200+处理器，安兔兔V10跑分超177万分，是目前安卓阵营最高的分数
印度登月最关键一步！月船三号今晚进入环月轨道

8月5日消息，据印度官方消息，月船三号将于北京时间今晚21时30分左右开始近月制动进入环月轨道。这是该探测器能够成功的最关键步骤之一，如果成功将开始围
得物效率前端微应用推进过程与思考

一、背景效率工程随着业务的发展，组织规模的扩大，越来越多的企业开始意识到协作效率对于企业团队的重要性，甚至是决定其在某个行业竞争中突围的关键，是企业长久生存的根本。得物
JavaScript学习 -AES加密算法

引言在当今数字化时代，前端应用程序扮演着重要角色，用户的敏感数据经常在前端进行加密和解密操作。然而，这样的操作在网络传输和存储中可能会受到恶意攻击的威胁。为了确保数据
破圈是B站头上的紧箍咒

来源 | 光子星球撰文 | 吴坤谚编辑 | 吴先之每年的暑期档都少不了瞄准追剧女孩们的古偶剧集，2021年有优酷的《山河令》，2022年有爱奇艺的《苍兰诀》，今年却轮到小破站抓住了追
华为Mate 60系列用上可变灵动岛：正式版体验将会更出色

这段时间以来，关于华为新旗舰的爆料日渐密集。据此前多方爆料，今年华为将开始恢复一年双旗舰战略，除上半年推出的P60系列外，往年下半年的Mate系列也将
国行版三星Galaxy Z Fold5/Z Flip5发布售价7499元起

2023年8月3日，三星电子举行Galaxy新品中国发布会，正式在国内推出了新一代折叠屏智能手机三星Galaxy Z Fold5与Galaxy Z Flip5，以及三星Galaxy Tab S9
外交部：美方应停止在网络安全问题上不负责任地指责他国

　中国外交部今天（16日）举行例行记者会。会上，有记者问，美国情报官员称，他们正在阻拦来自中国以及其他国家的黑客获取相关科研成果。中方对此有何评论？对此