Skip to content

Commit d456d9a

Browse files
YukiRinLLYukiRinLL
committed
add Swagger
1 parent 8c88a57 commit d456d9a

15 files changed

Lines changed: 597 additions & 295 deletions

‎src/main/java/com/phantoms/phantomsbackend/common/config/OpenApiConfig.java‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
package com.phantoms.phantomsbackend.common.config;
2+
3+
import io.swagger.v3.oas.models.OpenAPI;
4+
import io.swagger.v3.oas.models.info.Contact;
5+
import io.swagger.v3.oas.models.info.Info;
6+
import io.swagger.v3.oas.models.info.License;
7+
import io.swagger.v3.oas.models.security.SecurityRequirement;
8+
import io.swagger.v3.oas.models.security.SecurityScheme;
9+
import io.swagger.v3.oas.models.servers.Server;
10+
import org.springframework.context.annotation.Bean;
11+
import org.springframework.context.annotation.Configuration;
12+
13+
import java.util.List;
14+
15+
@Configuration
16+
public class OpenApiConfig {
17+
18+
@Bean
19+
public OpenAPI openAPI() {
20+
return new OpenAPI()
21+
.info(new Info()
22+
.title("Phantoms Backend API")
23+
.description("Phantoms后端服务API文档，提供完整的接口说明和测试功能")
24+
.version("1.0.0")
25+
.contact(new Contact()
26+
.name("Phantoms Team")
27+
.email("contact@phantoms.com")
28+
.url("https://phantoms.com"))
29+
.license(new License()
30+
.name("MIT License")
31+
.url("https://opensource.org/licenses/MIT")))
32+
.servers(List.of(
33+
new Server().url("http://localhost:8080").description("本地开发环境"),
34+
new Server().url("https://api.phantoms.com").description("生产环境")
35+
))
36+
.addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
37+
.components(new io.swagger.v3.oas.models.Components()
38+
.addSecuritySchemes("bearerAuth", new SecurityScheme()
39+
.type(SecurityScheme.Type.HTTP)
40+
.scheme("bearer")
41+
.bearerFormat("JWT")
42+
.description("JWT认证令牌")));
43+
}
44+
}

‎src/main/java/com/phantoms/phantomsbackend/common/config/SwaggerConfig.java‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎src/main/java/com/phantoms/phantomsbackend/controller/AuthUserController.java‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
import com.phantoms.phantomsbackend.pojo.entity.primary.AuthUser;
44
import com.phantoms.phantomsbackend.service.AuthUserService;
5+
import io.swagger.v3.oas.annotations.Operation;
6+
import io.swagger.v3.oas.annotations.tags.Tag;
57
import org.springframework.beans.factory.annotation.Autowired;
68
import org.springframework.web.bind.annotation.GetMapping;
79
import org.springframework.web.bind.annotation.RequestMapping;
@@ -11,13 +13,21 @@
1113

1214
@RestController
1315
@RequestMapping("/api/auth")
16+
@Tag(name = "Auth User", description = "认证用户管理接口")
1417
public class AuthUserController {
1518

1619
@Autowired
1720
private AuthUserService authUserService;
1821

1922
@GetMapping("/users")
23+
@Operation(
24+
summary = "获取所有认证用户",
25+
description = "获取系统中所有认证用户的列表",
26+
responses = {
27+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "获取用户列表成功")
28+
}
29+
)
2030
public List<AuthUser> getAllUsers() {
2131
return authUserService.getAllUsers();
2232
}
23-
}
33+
}

‎src/main/java/com/phantoms/phantomsbackend/controller/CacheController.java‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,33 @@
22

33
import com.alibaba.fastjson.JSONObject;
44
import com.phantoms.phantomsbackend.service.DaoYuKeyCacheService;
5+
import io.swagger.v3.oas.annotations.Operation;
6+
import io.swagger.v3.oas.annotations.tags.Tag;
57
import org.springframework.beans.factory.annotation.Autowired;
68
import org.springframework.web.bind.annotation.PostMapping;
79
import org.springframework.web.bind.annotation.RequestMapping;
810
import org.springframework.web.bind.annotation.RestController;
911

1012
@RestController
1113
@RequestMapping("/api/cache")
14+
@Tag(name = "Cache", description = "缓存管理接口")
1215
public class CacheController {
1316

1417
@Autowired
1518
private DaoYuKeyCacheService daoYuKeyCacheService;
1619

17-
/**
18-
* 手动刷新DaoYu Key缓存
19-
*/
2020
@PostMapping("/refresh-daoyu-key")
21+
@Operation(
22+
summary = "刷新DaoYu Key缓存",
23+
description = "手动刷新DaoYu Key缓存",
24+
responses = {
25+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "缓存刷新成功或失败")
26+
}
27+
)
2128
public JSONObject refreshDaoYuKeyCache() {
2229
JSONObject result = new JSONObject();
2330
try {
2431
daoYuKeyCacheService.evictDaoYuKeyCache();
25-
// 触发重新加载
2632
daoYuKeyCacheService.getDaoYuKey();
2733
result.put("success", true);
2834
result.put("message", "DaoYu Key缓存刷新成功");
@@ -33,21 +39,25 @@ public JSONObject refreshDaoYuKeyCache() {
3339
return result;
3440
}
3541

36-
/**
37-
* 获取缓存状态
38-
*/
3942
@PostMapping("/cache-status")
43+
@Operation(
44+
summary = "获取缓存状态",
45+
description = "获取当前DaoYu Key缓存的状态信息",
46+
responses = {
47+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "获取缓存状态成功或失败")
48+
}
49+
)
4050
public JSONObject getCacheStatus() {
4151
JSONObject result = new JSONObject();
4252
try {
4353
String currentKey = daoYuKeyCacheService.getDaoYuKey();
4454
result.put("success", true);
4555
result.put("cached", true);
46-
result.put("key", currentKey.substring(0, Math.min(10, currentKey.length())) + "***"); // 部分显示
56+
result.put("key", currentKey.substring(0, Math.min(10, currentKey.length())) + "***");
4757
} catch (Exception e) {
4858
result.put("success", false);
4959
result.put("message", "获取缓存状态失败: " + e.getMessage());
5060
}
5161
return result;
5262
}
53-
}
63+
}

‎src/main/java/com/phantoms/phantomsbackend/controller/D1Controller.java‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
import co.casterlabs.d1.result.D1Result;
44
import com.phantoms.phantomsbackend.service.D1Service;
5+
import io.swagger.v3.oas.annotations.Operation;
6+
import io.swagger.v3.oas.annotations.Parameter;
7+
import io.swagger.v3.oas.annotations.tags.Tag;
58
import org.springframework.beans.factory.annotation.Autowired;
69
import org.springframework.http.ResponseEntity;
710
import org.springframework.web.bind.annotation.*;
@@ -11,6 +14,7 @@
1114

1215
@RestController
1316
@RequestMapping("/api/d1")
17+
@Tag(name = "D1 Database", description = "Cloudflare D1数据库操作接口")
1418
public class D1Controller {
1519

1620
private final D1Service d1Service;
@@ -21,7 +25,16 @@ public D1Controller(D1Service d1Service) {
2125
}
2226

2327
@GetMapping("/query")
24-
public ResponseEntity<D1Result> query(@RequestParam String sql) {
28+
@Operation(
29+
summary = "执行单条SQL查询",
30+
description = "在Cloudflare D1数据库上执行单条SQL查询语句",
31+
responses = {
32+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
33+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "查询失败")
34+
}
35+
)
36+
public ResponseEntity<D1Result> query(
37+
@Parameter(description = "SQL查询语句", required = true) @RequestParam String sql) {
2538
try {
2639
D1Result result = d1Service.query(sql);
2740
return ResponseEntity.ok(result);
@@ -32,7 +45,16 @@ public ResponseEntity<D1Result> query(@RequestParam String sql) {
3245
}
3346

3447
@PostMapping("/batchQuery")
35-
public ResponseEntity<List<D1Result>> batchQuery(@RequestBody List<String> sqls) {
48+
@Operation(
49+
summary = "执行批量SQL查询",
50+
description = "在Cloudflare D1数据库上批量执行多条SQL查询语句",
51+
responses = {
52+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "批量查询成功"),
53+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "批量查询失败")
54+
}
55+
)
56+
public ResponseEntity<List<D1Result>> batchQuery(
57+
@Parameter(description = "SQL查询语句列表", required = true) @RequestBody List<String> sqls) {
3658
try {
3759
D1Result[] results = d1Service.batchQuery(sqls);
3860
return ResponseEntity.ok(Arrays.asList(results));
@@ -41,4 +63,4 @@ public ResponseEntity<List<D1Result>> batchQuery(@RequestBody List<String> sqls)
4163
return ResponseEntity.badRequest().body(null);
4264
}
4365
}
44-
}
66+
}

‎src/main/java/com/phantoms/phantomsbackend/controller/EmailController.java‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,14 @@ public class EmailController {
2525
private EmailService emailService;
2626

2727
@GetMapping("/send-test-email")
28+
@Operation(
29+
summary = "Send test email",
30+
description = "Sends a test email to the specified recipient",
31+
responses = {
32+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Test email sent successfully"),
33+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid email address")
34+
}
35+
)
2836
public ResponseEntity<String> sendEmail(@RequestParam String to) {
2937
String subject = "Test Subject";
3038
Map<String, Object> templateVariables = new HashMap<>();
@@ -44,7 +52,11 @@ public ResponseEntity<String> sendEmail(@RequestParam String to) {
4452
@PostMapping("/send-email-to-all")
4553
@Operation(
4654
summary = "Send email to all users",
47-
description = "Send an email to all registered users with the specified subject and text"
55+
description = "Send an email to all registered users with the specified subject and text",
56+
responses = {
57+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Email sent to all users successfully"),
58+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "500", description = "Failed to send email")
59+
}
4860
)
4961
public ResultInfo<String> sendEmailToAllUsers(@RequestBody EmailContent emailContent) {
5062
emailService.sendEmailToAllUsers(emailContent.getSubject(), emailContent.getText());
@@ -58,6 +70,14 @@ private static class EmailContent {
5870
}
5971

6072
@PostMapping("/auth-user-info")
73+
@Operation(
74+
summary = "Send auth user info email",
75+
description = "Sends authentication user information email to the specified email address",
76+
responses = {
77+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Auth user info email sent successfully"),
78+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid email address")
79+
}
80+
)
6181
public String newUser(@RequestBody AuthUserEmailDTO authUserEmailDTO) {
6282
emailService.sendAuthUserDetailEmail(authUserEmailDTO.getEmail());
6383
System.out.println("Auth user info sent: " + authUserEmailDTO.getEmail());

‎src/main/java/com/phantoms/phantomsbackend/controller/ImageProxyController.java‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
package com.phantoms.phantomsbackend.controller;
22

3+
import io.swagger.v3.oas.annotations.Operation;
4+
import io.swagger.v3.oas.annotations.Parameter;
5+
import io.swagger.v3.oas.annotations.tags.Tag;
36
import jakarta.servlet.http.HttpServletRequest;
47
import lombok.extern.log4j.Log4j2;
58
import okhttp3.*;
@@ -26,25 +29,31 @@
2629

2730
@Log4j2
2831
@RestController
32+
@Tag(name = "Image Proxy", description = "图片代理接口")
2933
public class ImageProxyController {
3034

3135
private final OkHttpClient client;
3236

3337
@Autowired
3438
public ImageProxyController() {
35-
// 配置 OkHttpClient 使用连接池
3639
client = new OkHttpClient.Builder()
3740
.connectTimeout(30, TimeUnit.SECONDS)
3841
.writeTimeout(30, TimeUnit.SECONDS)
3942
.readTimeout(30, TimeUnit.SECONDS)
4043
.build();
4144
}
4245

43-
/*
44-
* 图片代理对内存消耗过大，不要在Rrnder上使用这个接口方法，会导致OOM
45-
* */
4646
@GetMapping("/proxy/image")
47-
public ResponseEntity<byte[]> proxyImage(@RequestParam String url) throws IOException {
47+
@Operation(
48+
summary = "图片代理",
49+
description = "代理获取指定URL的图片资源。注意：此接口对内存消耗较大，不建议在生产环境频繁使用",
50+
responses = {
51+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "图片获取成功"),
52+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "图片获取失败")
53+
}
54+
)
55+
public ResponseEntity<byte[]> proxyImage(
56+
@Parameter(description = "图片URL", required = true) @RequestParam String url) throws IOException {
4857
URL imageUrl = new URL(url);
4958
HttpURLConnection connection = (HttpURLConnection) imageUrl.openConnection();
5059
connection.setRequestMethod("GET");
@@ -65,7 +74,16 @@ public ResponseEntity<byte[]> proxyImage(@RequestParam String url) throws IOExce
6574
}
6675

6776
@GetMapping("/proxy/qqemoji")
68-
public ResponseEntity<StreamingResponseBody> proxyQQEmoji(@RequestParam String faceId) {
77+
@Operation(
78+
summary = "QQ表情代理",
79+
description = "代理获取QQ表情图片",
80+
responses = {
81+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "表情获取成功"),
82+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "表情获取失败")
83+
}
84+
)
85+
public ResponseEntity<StreamingResponseBody> proxyQQEmoji(
86+
@Parameter(description = "表情ID", required = true) @RequestParam String faceId) {
6987
String imageUrl = "https://q1.qlogo.cn/qqemoji/qq/" + faceId + ".gif";
7088
Request request = new Request.Builder()
7189
.url(imageUrl)
@@ -78,9 +96,6 @@ private ResponseEntity<StreamingResponseBody> handleRequest(Request request) {
7896
try (Response response = client.newCall(request).execute()) {
7997
if (response.isSuccessful() && response.body() != null) {
8098
long contentLength = response.body().contentLength();
81-
// if (contentLength > 10 * 1024 * 1024) { // 限制图片大小为10MB
82-
// return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE).body(null);
83-
// }
8499

85100
StreamingResponseBody stream = outputStream -> {
86101
try (InputStream inputStream = response.body().byteStream()) {
@@ -106,4 +121,4 @@ private ResponseEntity<StreamingResponseBody> handleRequest(Request request) {
106121
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(null);
107122
}
108123
}
109-
}
124+
}

0 commit comments

Comments
 (0)