Skip to content

Commit 30e0e60

Browse files
ClearAzureClearAzure
committed
增加api文档注释
1 parent c8d964c commit 30e0e60

5 files changed

Lines changed: 34 additions & 6 deletions

File tree

‎drawbluecup-common/src/main/java/com/drawbluecup/entity/User.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515

1616
//实体层封装数据,用于存储,取出及使用
1717
//而Result层用于封装返回数据
18+
1819
public class User {
1920

2021
private Integer id ;

‎drawbluecup-web/src/main/java/com/drawbluecup/web/config/GlobalCorsConfig.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,9 @@ public WebMvcConfigurer corsConfigurer() {
1717
@Override
1818
public void addCorsMappings(CorsRegistry registry) {
1919
registry.addMapping("/**")
20-
.allowedOrigins("http://127.0.0.1:5500")
20+
.allowedOrigins("http://127.0.0.1:5500")//npx http-server -p 5500
21+
// 127.0.0.1 是 本地回环地址（也叫 “localhost”）
22+
// 输入 http://localhost:5500 和 http://127.0.0.1:5500，效果一模一样
2123
.allowedMethods("GET", "POST", "PUT", "DELETE")
2224
.allowedHeaders("Content-Type", "Authorization")
2325
.allowCredentials(true)

‎drawbluecup-web/src/main/java/com/drawbluecup/web/controller/OrderController.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ public Result<List<Order>> findOrderAll() {
4848
*
4949
*/
5050
@GetMapping("/findUserWithOrders/{id}")
51+
@Operation(summary = "根据用户id查询用户以及所对应订单", description = "实现根据用户id查询用户以及所对应订单")
52+
5153
public Result<User> findUserWithOrders(
5254
@Parameter(description = "用户 ID", required = true)
5355
@PathVariable Integer id){
@@ -62,6 +64,7 @@ public Result<User> findUserWithOrders(
6264
*/
6365

6466
@PostMapping("/add")
67+
@Operation(summary = "新增商品", description = "不需要传输自增id")
6568
public Result<Void> addOrder(@RequestBody Order order)
6669
{
6770

@@ -76,6 +79,7 @@ public Result<Void> addOrder(@RequestBody Order order)
7679
* 前端想删除所有订单，通过这个接口删除数据库里的记录
7780
*/
7881
@DeleteMapping("/deleteAll")
82+
@Operation(summary = "删除所有订单(慎重)")
7983
public Result<Void> deleteOrderAll()
8084
{
8185

@@ -111,8 +115,10 @@ public Result<Order> findOrderWithProducts(
111115
* @param productId 商品ID（路径变量）
112116
* @return 操作结果
113117
*/
118+
114119
@PostMapping("/{orderId}/products/{productId}")
115120
@Operation(summary = "为订单添加商品", description = "将指定商品添加到指定订单中，建立订单与商品的多对多关联")
121+
116122
public Result<Void> addProductToOrder(
117123
@Parameter(description = "订单ID", required = true)
118124
@PathVariable Integer orderId,

‎drawbluecup-web/src/main/java/com/drawbluecup/web/controller/ProductController.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import com.drawbluecup.entity.Product;
44
import com.drawbluecup.result.Result;
55
import com.drawbluecup.service.ProductService;
6+
import io.swagger.v3.oas.annotations.Operation;
67
import io.swagger.v3.oas.annotations.tags.Tag;
78
import org.springframework.beans.factory.annotation.Autowired;
89
import org.springframework.web.bind.annotation.*;
@@ -36,6 +37,7 @@ public class ProductController {
3637
* 无参数，返回商品列表
3738
*/
3839
@GetMapping("/findAll")
40+
@Operation(summary = "查询所有商品")
3941
public Result<List<Product>> findAll(){
4042
return Result.success(200,"查询成功" , productService.findAll());
4143
}
@@ -47,6 +49,7 @@ public Result<List<Product>> findAll(){
4749
* 参数id，返回商品列表
4850
*/
4951
@GetMapping("/findById/{id}")
52+
@Operation(summary = "根据id查询商品", description = "根据商品ID查询商品信息")
5053
public Result<Product> findById(@PathVariable Integer id){
5154
return Result.success(200,"查询成功" , productService.findById(id));
5255
}
@@ -58,6 +61,7 @@ public Result<Product> findById(@PathVariable Integer id){
5861
* 参数name，返回商品列表
5962
*/
6063
@GetMapping("/findByName/{name}")
64+
@Operation(summary = "根据name查询商品", description = "根据商品name查询商品信息")
6165
public Result<Product> findByName(@PathVariable String name){
6266
return Result.success(200,"查询成功" , productService.findByName(name));
6367
}
@@ -69,6 +73,7 @@ public Result<Product> findByName(@PathVariable String name){
6973
* 无参数，无返回
7074
*/
7175
@DeleteMapping("/deleteAll")
76+
@Operation(summary = "删除所有商品（慎重）")
7277
public Result<Void> deleteAll(){
7378
productService.deleteAll();//不能写在下面,因为不返回值
7479
return Result.success(200,"删除所有商品成功",null);
@@ -80,7 +85,9 @@ public Result<Void> deleteAll(){
8085
* 请求方式：Delete
8186
* 参数id，无返回
8287
*/
88+
8389
@DeleteMapping("/deleteById/{id}")
90+
@Operation(summary = "基于id删除商品")
8491
public Result<Void> deleteById(@PathVariable Integer id){
8592
productService.deleteById(id);
8693
return Result.success(200,"删除成功",null);
@@ -93,6 +100,7 @@ public Result<Void> deleteById(@PathVariable Integer id){
93100
* 参数对象(不用包含id,自增)，无返回
94101
*/
95102
@PostMapping("/add")
103+
@Operation(summary = "新增商品", description = "不需要传输自增id")
96104
public Result<Void> add(@RequestBody Product product){
97105
productService.add(product);
98106
return Result.success(201,"添加成功",null);
@@ -105,6 +113,7 @@ public Result<Void> add(@RequestBody Product product){
105113
* 参数对象(其中包含id和其他字段,id用来定位,其他是修改)，无返回
106114
*/
107115
@PutMapping("/update")
116+
@Operation(summary = "基于id查询修改单个商品")
108117
public Result<Void> update(@RequestBody Product product){
109118
productService.update(product);
110119
return Result.success(200,"修改成功",null);

‎drawbluecup-web/src/main/java/com/drawbluecup/web/controller/UserController.java‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,14 @@
88
import com.drawbluecup.validation.Phone;
99

1010
import com.github.pagehelper.PageInfo;
11+
import io.swagger.v3.oas.annotations.Operation;
1112
import io.swagger.v3.oas.annotations.tags.Tag;
1213
import jakarta.validation.Valid;
1314
import org.springframework.beans.factory.annotation.Autowired;
1415
import org.springframework.validation.annotation.Validated;
1516
import org.springframework.web.bind.annotation.*;
1617

18+
import org.springframework.web.bind.annotation.GetMapping;
1719
import java.time.LocalDateTime;
1820
import java.util.List;
1921

@@ -38,14 +40,16 @@ public class UserController {
3840
@Autowired
3941
private UserService userService;//依赖的是接口（UserService）而不是实现类
4042

41-
/*
43+
/**
4244
* 查询所有用户
4345
* 接口路径：/api/user/findAll
4446
* 请求方式：GET
4547
* 无参数，返回用户列表
4648
*/
4749

48-
@GetMapping("/findAll") // 接收 GET 请求，子路径是 /findAll
50+
@GetMapping("/findAll")// 接收 GET 请求，子路径是 /findAll
51+
@Operation(summary = "查询所有用户", description = "查询所有用户以及和用户相关的数据")
52+
4953
public Result<List<User>> findUserAll() {
5054
// 调用 Service 的 findAll() 方法，获取结果并返回给前端
5155
return Result.success(200,"查询成功",userService.findAll());
@@ -56,13 +60,14 @@ public Result<List<User>> findUserAll() {
5660

5761

5862

59-
/*
63+
/**
6064
* 2.0实现“根据ID查询单个用户”功能
6165
* 业务逻辑：先校验ID是否合法，再查数据库，最后校验结果是否存在
6266
*/
6367

6468
//示例:http://localhost:8080/api/user/findById/6
6569
@GetMapping("/findById/{id}")
70+
@Operation(summary = "根据ID查询单个用户")
6671
public Result<User> findById(@PathVariable Integer id){
6772

6873
return Result.success(200,"查询成功",userService.findById(id));
@@ -71,12 +76,13 @@ public Result<User> findById(@PathVariable Integer id){
7176
}
7277

7378

74-
/*
79+
/**
7580
* 接口2.1实现“根据phone查询单个用户”功能
7681
* 业务逻辑：先校验phone是否合法，再查数据库，最后校验结果是否存在
7782
*/
7883
//示例:http://localhost:8080/api/user/findByPhone/{phone}
7984
@GetMapping("/findByPhone/{phone}")
85+
@Operation(summary = "根据phone查询单个用户")
8086
public Result<User> findByPhone(@PathVariable @Phone String phone){
8187
return Result.success(200,"查询成功",userService.findByPhone(phone));
8288

@@ -92,6 +98,7 @@ public Result<User> findByPhone(@PathVariable @Phone String phone){
9298
*
9399
*/
94100
@GetMapping("/query")
101+
@Operation(summary = "条件模糊分页查询",description = "可以多个模糊条件组合查询，拥有分页功能")
95102
public Result<PageInfo<User>> queryUserByCondition(
96103
@RequestParam(required = false) String name, // required=false：参数可选
97104
@RequestParam(required = false) String phone,
@@ -118,7 +125,7 @@ public Result<PageInfo<User>> queryUserByCondition(
118125

119126
//示例:http://localhost:8080/api/user/add
120127
@PostMapping("/add")
121-
128+
@Operation(summary = "新增用户")
122129
// @RequestBody User user：把前端传来的JSON格式数据，自动转成User对象//接受前端
123130
// （比如前端传{"name":"张三","phone":"123"}，这里就会得到一个name=张三、phone=123的User对象）
124131

@@ -143,6 +150,7 @@ public Result<Void> addUser (@Valid @RequestBody User user)
143150

144151
//示例:http://localhost:8080/api/user/update
145152
@PutMapping("/update")
153+
@Operation(summary = "基于id查询修改单个用户")
146154
//@RequestBody User user：接收前端传来的JsoN，转成User对象
147155
public Result<Void> updateUser(@Valid @RequestBody User user)
148156
{
@@ -165,6 +173,7 @@ public Result<Void> updateUser(@Valid @RequestBody User user)
165173
@DeleteMapping("/delete/{id}")
166174
//通过路径来输入/接收
167175
//{id} 是路径变量，对应前端传递的用户ID（比如请求 /delete/1 表示删除ID=1的用户）
176+
@Operation(summary = "基于id删除单个用户")
168177
public Result<Void> deleteUser(@PathVariable Integer id)
169178
{
170179
userService.deleteUser(id);
@@ -179,6 +188,7 @@ public Result<Void> deleteUser(@PathVariable Integer id)
179188
* 前端想删除所有用户，通过这个接口删除数据库里的记录
180189
*/
181190
@DeleteMapping("/deleteUserAll")
191+
@Operation(summary = "删除所有用户（慎重）")
182192
public Result<Void> deleteUserAll()
183193
{
184194

0 commit comments

Comments
 (0)