在线编辑器运行:mvn spring-boot:run
进入正文
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