spring boot 基础案例【4】使用Swagger2构建强大的API文档

2024-05-11 23:20
文章标签 java 基础 文档 使用 构建 spring 强大 api boot 案例 swagger2

本文主要是介绍spring boot 基础案例【4】使用Swagger2构建强大的API文档，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

教程1
案例教程
案例仓库
在线编程

在线编辑器运行：mvn spring-boot:run

教程2
基础教程
教程仓库
在线编程

本案例所在的仓库
本案例所在的文档

进入正文

1.文件目录

在这里插入图片描述

2.应用主类

地址:2.x/chapter2-2/src/main/java/com/didispace/chapter22/Chapter22Application.java

// 定义该类所属的包
package com.didispace.chapter22;// 导入必要的类和注解，这些来自外部的库
import com.spring4all.swagger.EnableSwagger2Doc;  // 导入注解，用于启用spring4all版本的Swagger文档
import org.springframework.boot.SpringApplication;  // 导入类，用于运行Spring Boot应用程序
import org.springframework.boot.autoconfigure.SpringBootApplication;  // 导入注解，用于简化Spring应用程序的配置// 启用Swagger 2文档，这样我们就可以通过Swagger UI查看和测试API
@EnableSwagger2Doc// 这是一个组合注解，它包含了多个Spring Boot注解，如@Configuration、@EnableAutoConfiguration和@ComponentScan
// 它通常用于主应用程序类，以简化配置并自动配置Spring应用程序
@SpringBootApplication
public class Chapter22Application {// 主方法，Spring Boot应用程序的入口点public static void main(String[] args) {// 使用SpringApplication类的run方法来启动Spring Boot应用程序// Chapter22Application.class作为应用程序上下文的源，args作为传递给应用程序的命令行参数SpringApplication.run(Chapter22Application.class, args);}}

3.pom.xml

地址：2.x/chapter2-2/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.didispace</groupId><artifactId>chapter2-2</artifactId><version>0.0.1-SNAPSHOT</version><name>chapter2-2</name><description>使用Swagger2构建强大的API文档</description><properties><java.version>1.8</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.spring4all</groupId><artifactId>swagger-spring-boot-starter</artifactId><version>1.9.0.RELEASE</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>

4. 模型

地址：2.x/chapter2-2/src/main/java/com/didispace/chapter22/User.java

package com.didispace.chapter22;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;/*** 使用@Data注解来自动生成getter和setter方法，以及equals、canEqual、hashCode、toString方法。* 这个类定义了一个简单的用户实体，用于Swagger文档化。* * @ApiModelProperty注解用于描述模型属性的元数据。*/
@Data
@ApiModel(description = "用户实体")
public class User {/*** 用户编号，用于唯一标识用户。*/@ApiModelProperty("用户编号")private Long id;/*** 用户姓名，用于表示用户的姓名。*/@ApiModelProperty("用户姓名")private String name;/*** 用户年龄，用于表示用户的年龄。*/@ApiModelProperty("用户年龄")private Integer age;public User(Long id, String name, int age) {this.id = id;this.name = name;this.age = age;}}

5.控制器

地址:chapter2-2/src/main/java/com/didispace/chapter22/UserController.java

package com.didispace.chapter22;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;import java.util.*;/*** 用户控制器，用于管理用户相关的操作。* 提供创建、获取、更新和删除用户信息的API端点。* 使用Swagger注解来增强API文档。*/
@Api(tags = "用户管理")
@RestController  // 标记该类为REST控制器，每个方法返回一个域对象而不是视图。
@RequestMapping(value = "/users") // 映射HTTP请求到MVC和REST控制器的处理方法。
public class UserController {// 创建一个线程安全的Map，模拟用户信息的存储。static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());static {User user1 = new User(1566L, "Alice", 25);User user2 = new User(2L, "Bob", 30);User user3 = new User(3L, "Charlie", 35);users.put(user1.getId(), user1);users.put(user2.getId(), user2);users.put(user3.getId(), user3);}/*** 获取所有用户列表。* * @return 用户对象列表。*/@GetMapping("/")@ApiOperation(value = "获取用户列表", notes = "返回所有用户的列表")public List<User> getUserList() {return new ArrayList<>(users.values());}/*** 创建新用户。* * @param user 请求体中的用户对象。* @return 操作成功字符串。*/@PostMapping("/")@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")public String postUser(@RequestBody User user) {users.put(user.getId(), user);return "success";}/*** 获取特定用户的详细信息。* * @param id 用户的ID。* @return 具有指定ID的用户对象。*/@GetMapping("/{id}")@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")public User getUser(@PathVariable Long id) {return users.get(id);}/*** 更新特定用户的信息。* * @param id 用户的ID。* @param user 请求体中的更新用户信息。* @return 更新操作成功字符串。*/@PutMapping("/{id}")@ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")@ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")public String putUser(@PathVariable Long id, @RequestBody User user) {User u = users.get(id);if (u != null) {u.setName(user.getName());u.setAge(user.getAge());users.put(id, u);return "success";}return "fail";}/*** 删除特定用户。* * @param id 用户的ID。* @return 删除操作成功字符串。*/@DeleteMapping("/{id}")@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")public String deleteUser(@PathVariable Long id) {if (users.remove(id) != null) {return "success";}return "fail";}
}

中文注释说明

这段代码已经添加了详细的中文注释，每个注释都旨在帮助读者理解代码的功能和意图。注释包括：

  • 类级别的注释：描述了UserController类的整体目的，包括它作为REST控制器的角色以及使用Swagger进行API文档增强。

  • 字段级别的注释：解释了users映射的目的，它模拟了用户信息的数据库。

  • 方法级别的注释：每个方法都附有注释，描述了方法的目的、参数和返回值。这些注释还包括了Swagger注解的相关说明。

通过这种方式添加注释，代码的可维护性和可理解性得到了显著提高，特别是对于那些可能不熟悉项目或依赖自动生成API文档来有效使用端点的开发者来说。

6. Swagger配置文件

地址：chapter2-2/src/main/resources/application.properties

这段代码是一个配置文件，用于配置Swagger的相关信息。Swagger是一个用于设计、构建和文档化RESTful风格的Web服务的工具。

下面是对这段代码的详细解释：

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.9.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
swagger.contact.email=dyc87112@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**

  • swagger.title：Swagger文档的标题，这里设置为"spring-boot-starter-swagger"。

  • swagger.description：Swagger文档的描述，这里设置为"Starter for swagger 2.x"。

  • swagger.version：Swagger文档的版本号，这里设置为"1.9.0.RELEASE"。

  • swagger.license：Swagger文档的许可证，这里设置为"Apache License, Version 2.0"。

  • swagger.licenseUrl：Swagger文档许可证的URL，这里设置为"https://www.apache.org/licenses/LICENSE-2.0.html"。

  • swagger.termsOfServiceUrl：Swagger文档的服务条款URL，这里设置为"https://github.com/dyc87112/spring-boot-starter-swagger"。

  • swagger.contact.name：Swagger文档的联系人姓名，这里设置为"didi"。

  • swagger.contact.url：Swagger文档的联系人URL，这里设置为"http://blog.didispace.com"。

  • swagger.contact.email：Swagger文档的联系人邮箱，这里设置为"dyc87112@qq.com"。

  • swagger.base-package：指定需要生成API文档的基础包路径，这里设置为"com.didispace"。

  • swagger.base-path：指定API的基础路径，这里设置为"/**"，表示所有的API都会被包含在文档中。

通过这些配置，Swagger可以生成一个包含API接口信息的文档，方便开发人员查看和测试API。

7.效果图

http://localhost:8080/swagger-ui.html
在这里插入图片描述
在这里插入图片描述

这篇关于spring boot 基础案例【4】使用Swagger2构建强大的API文档的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！


http://www.chinasem.cn/article/980947。

相关文章

C++使用栈实现括号匹配的代码详解

C++使用栈实现括号匹配的代码详解

《C++使用栈实现括号匹配的代码详解》在编程中,括号匹配是一个常见问题,尤其是在处理数学表达式、编译器解析等任务时,栈是一种非常适合处理此类问题的数据结构,能够精确地管理括号的匹配问题,本文将通过C+... 目录引言问题描述代码讲解代码解析栈的状态表示测试总结引言在编程中，括号匹配是一个常见问题，尤其是在
阅读更多...
Java实现检查多个时间段是否有重合

Java实现检查多个时间段是否有重合

《Java实现检查多个时间段是否有重合》这篇文章主要为大家详细介绍了如何使用Java实现检查多个时间段是否有重合,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起学习一下... 目录流程概述步骤详解China编程步骤1：定义时间段类步骤2：添加时间段步骤3：检查时间段是否有重合步骤4：输出结果示例代码结语作
阅读更多...
Java中String字符串使用避坑指南

Java中String字符串使用避坑指南

《Java中String字符串使用避坑指南》Java中的String字符串是我们日常编程中用得最多的类之一,看似简单的String使用,却隐藏着不少“坑”,如果不注意,可能会导致性能问题、意外的错误容... 目录8个避坑点如下：1. 字符串的不可变性：每次修改都创建新对象2. 使用 == 比较字符串，陷阱满
阅读更多...
Java判断多个时间段是否重合的方法小结

Java判断多个时间段是否重合的方法小结

《Java判断多个时间段是否重合的方法小结》这篇文章主要为大家详细介绍了Java中判断多个时间段是否重合的方法,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起学习一下... 目录判断多个时间段是否有间隔判断时间段集合是否与某时间段重合判断多个时间段是否有间隔实体类内容public class D
阅读更多...
Python使用国内镜像加速pip安装的方法讲解

Python使用国内镜像加速pip安装的方法讲解

《Python使用国内镜像加速pip安装的方法讲解》在Python开发中,pip是一个非常重要的工具,用于安装和管理Python的第三方库,然而,在国内使用pip安装依赖时,往往会因为网络问题而导致速... 目录一、pip 工具简介1. 什么是 pip？2. 什么是 -i 参数？二、国内镜像源的选择三、如何
阅读更多...
使用C++实现链表元素的反转

使用C++实现链表元素的反转

《使用C++实现链表元素的反转》反转链表是链表操作中一个经典的问题,也是面试中常见的考题,本文将从思路到实现一步步地讲解如何实现链表的反转,帮助初学者理解这一操作,我们将使用C++代码演示具体实现,同... 目录问题定义思路分析代码实现带头节点的链表代码讲解其他实现方式时间和空间复杂度分析总结问题定义给定
阅读更多...
IDEA编译报错“java: 常量字符串过长”的原因及解决方法

IDEA编译报错“java: 常量字符串过长”的原因及解决方法

《IDEA编译报错“java:常量字符串过长”的原因及解决方法》今天在开发过程中,由于尝试将一个文件的Base64字符串设置为常量,结果导致IDEA编译的时候出现了如下报错java:常量字符串过长,... 目录一、问题描述二、问题原因2.1 理论角度2.2 源码角度三、解决方案解决方案①：StringBui
阅读更多...
Linux使用nload监控网络流量的方法

Linux使用nload监控网络流量的方法

《Linux使用nload监控网络流量的方法》Linux中的nload命令是一个用于实时监控网络流量的工具,它提供了传入和传出流量的可视化表示,帮助用户一目了然地了解网络活动,本文给大家介绍了Linu... 目录简介安装示例用法基础用法指定网络接口限制显示特定流量类型指定刷新率设置流量速率的显示单位监控多个
阅读更多...
Java覆盖第三方jar包中的某一个类的实现方法

Java覆盖第三方jar包中的某一个类的实现方法

《Java覆盖第三方jar包中的某一个类的实现方法》在我们日常的开发中,经常需要使用第三方的jar包,有时候我们会发现第三方的jar包中的某一个类有问题,或者我们需要定制化修改其中的逻辑,那么应该如何... 目录一、需求描述二、示例描述三、操作步骤四、验证结果五、实现原理一、需求描述需求描述如下：需要在
阅读更多...
Java中ArrayList和LinkedList有什么区别举例详解

Java中ArrayList和LinkedList有什么区别举例详解

《Java中ArrayList和LinkedList有什么区别举例详解》：本文主要介绍Java中ArrayList和LinkedList区别的相关资料,包括数据结构特性、核心操作性能、内存与GC影... 目录一、底层数据结构二、核心操作性能对比三、内存与 GC 影响四、扩容机制五、线程安全与并发方案六、工程
阅读更多...

Copyright China编程 23002807@qq.com

沪ICP备2023033072号-2