fix: loading icon

feat(docs): show API routes on overview

.github/ISSUE_TEMPLATE/新功能建议.md

@@ -1,10 +1,9 @@
 ---
 name: 新功能建议
 about: 请为该项目提出一个想法
-title: ''
+title: ""
-labels: ''
+labels: ""
-assignees: ''
+assignees: ""
-
 ---
 
 **你的功能请求是否与某个问题相关？请描述。**

.github/ISSUE_TEMPLATE/错误-bug报告.md

@@ -1,10 +1,9 @@
 ---
 name: 错误/Bug报告
 about: 创建报告以帮助我们改进
-title: ''
+title: ""
-labels: ''
+labels: ""
-assignees: ''
+assignees: ""
-
 ---
 
 **描述 Bug**
@@ -26,16 +25,16 @@ assignees: ''
 
 **桌面端（请完成以下信息）：**
 
-* 操作系统：\[例如 iOS]
+- 操作系统：\[例如 iOS]
-* 浏览器：\[例如 Chrome、Safari]
+- 浏览器：\[例如 Chrome、Safari]
-* 版本：\[例如 22]
+- 版本：\[例如 22]
 
 **移动端（请完成以下信息）：**
 
-* 设备：\[例如 iPhone6]
+- 设备：\[例如 iPhone6]
-* 操作系统：\[例如 iOS8.1]
+- 操作系统：\[例如 iOS8.1]
-* 浏览器：\[例如 系统自带浏览器、Safari]
+- 浏览器：\[例如 系统自带浏览器、Safari]
-* 版本：\[例如 22]
+- 版本：\[例如 22]
 
 **附加上下文**
 在此添加与问题相关的其他上下文信息。

.github/workflows/deploy-staging.yml

@@ -12,6 +12,7 @@ jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
     environment: Deploy
+    if: ${{ !github.event.repository.fork }} # 只有非 fork 才执行
 
     steps:
       - uses: actions/checkout@v4
@@ -31,4 +32,3 @@ jobs:
     secrets: inherit
     with:
       build-id: ${{ github.run_id }}
-

CONTRIBUTING.md

@@ -4,6 +4,8 @@
     - [配置环境变量](#配置环境变量)
     - [配置 IDEA 参数](#配置-idea-参数)
     - [配置 MySQL](#配置-mysql)
+    - [配置 Redis](#配置-redis)
+    - [配置 RabbitMQ](#配置-rabbitmq)
   - [Docker 环境](#docker-环境)
     - [配置环境变量](#配置环境变量-1)
     - [构建并启动镜像](#构建并启动镜像)
@@ -11,6 +13,13 @@
   - [配置环境变量](#配置环境变量-2)
   - [安装依赖和运行](#安装依赖和运行)
 - [其他配置](#其他配置)
+  - [配置第三方登录以GitHub为例](#配置第三方登录以GitHub为例)
+  - [配置Resend邮箱服务](#配置Resend邮箱服务)
+- [API文档](#api文档)
+  - [OpenAPI文档](#openapi文档)
+  - [部署时间线以及文档时效性](#部署时间线以及文档时效性)
+  - [OpenAPI文档使用](#OpenAPI文档使用)
+  - [OpenAPI文档应用场景](#OpenAPI文档应用场景)
 
 ## 前置工作
 
@@ -88,9 +97,8 @@ SERVER_PORT=8082
 > 如果不知道怎么配置数据库可以参考 [Docker 环境](#docker-环境) 章节
 
 1. 本机配置 MySQL 服务（网上很多教程，忽略）
-
+   - 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 `6.x`，`7` 以后需要 Lisence
-    + 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 `6.x`，`7` 以后需要 Lisence
+   - [下载地址](https://github.com/leokhoa/laragon/releases)
-    + [下载地址](https://github.com/leokhoa/laragon/releases)
 
 2. 填写环境变量
 
@@ -111,14 +119,75 @@ SERVER_PORT=8082
 
 #### 配置 Redis
 
-填写环境变量 `.env` 中的 Redis 相关配置并启动 Redis
+后端的登录态缓存、访问频控等都依赖 Redis，请确保本地有可用的 Redis 实例。
 
-```ini
+1. **启动 Redis 服务**（已有服务可跳过）
-REDIS_HOST=<Redis 地址>
+
-REDIS_PORT=<Redis 端口>
+   ```bash
+   docker run --name openisle-redis -p 6379:6379 -d redis:7-alpine
    ```
 
-处理完环境问题直接跑起来就能通了
+   该命令会在本机暴露 `6379` 端口。若你已有其他端口的 Redis，可以根据实际情况调整映射关系。
+
+2. **在 `backend/open-isle.env` 中填写连接信息**
+
+   ```ini
+   REDIS_HOST=127.0.0.1
+   REDIS_PORT=6379
+   # 可选：若需要切换逻辑库，可新增此变量，默认使用 0 号库
+   REDIS_DATABASE=0
+   ```
+
+   `application.properties` 中的默认值为 `localhost:6379`、数据库 `0`，如果你的环境恰好一致，也可以不额外填写；显式声明可以避免 IDE/运行时读取到意外配置。
+
+3. **验证连接**
+
+   ```bash
+   redis-cli -h 127.0.0.1 -p 6379 ping
+   ```
+
+   启动后端后，日志中会出现 `Redis connection established ...`（来自 `RedisConnectionLogger`），说明已成功连通。
+
+#### 配置 RabbitMQ
+
+消息通知和 WebSocket 推送链路依赖 RabbitMQ。后端会自动声明交换机与队列，确保本地 RabbitMQ 可用即可。
+
+1. **启动 RabbitMQ 服务**（推荐包含管理界面）
+
+   ```bash
+   docker run --name openisle-rabbitmq \
+     -e RABBITMQ_DEFAULT_USER=openisle \
+     -e RABBITMQ_DEFAULT_PASS=openisle \
+     -p 5672:5672 -p 15672:15672 \
+     -d rabbitmq:3.13-management
+   ```
+
+   管理界面位于 http://127.0.0.1:15672 ，可用于查看队列、交换机等资源。
+
+2. **同步填写后端与 WebSocket 服务的环境变量**
+
+   ```ini
+   # backend/open-isle.env
+   RABBITMQ_HOST=127.0.0.1
+   RABBITMQ_PORT=5672
+   RABBITMQ_USERNAME=openisle
+   RABBITMQ_PASSWORD=openisle
+
+   # 如果需要启动 websocket_service，也需要在 websocket_service.env 中保持一致
+   ```
+
+   如果沿用 RabbitMQ 默认的 `guest/guest`，可以不显式设置，Spring Boot 会回退到 `application.properties` 中的默认值 (`localhost:5672`、`guest/guest`、虚拟主机 `/`)。
+
+3. **确认自动声明的资源**
+
+   - 交换机：`openisle-exchange`
+   - 旧版兼容队列：`notifications-queue`
+   - 分片队列：`notifications-queue-0` ~ `notifications-queue-f`（共 16 个，对应路由键 `notifications.shard.0` ~ `notifications.shard.f`）
+   - 队列持久化默认开启，来自 `rabbitmq.queue.durable=true`，如需仅在本地短暂测试，可在 `application.properties` 中调整该配置。
+
+   启动后端时可在日志中看到 `=== 开始主动声明 RabbitMQ 组件 ===` 与后续的声明结果，也可以在管理界面中查看是否创建成功。
+
+完成 Redis 与 RabbitMQ 配置后，即可继续启动后端服务。
 
 ![运行画面](assets/contributing/backend_img_4.png)
 
@@ -210,7 +279,7 @@ npm run dev
 
 ## 其他配置
 
-### 配置第三方登录，这里以 GitHub 为例：
+### 配置第三方登录以GitHub为例
 
 - 修改 `application.properties` 配置
 
@@ -246,3 +315,43 @@ https://resend.com/emails 创建账号并登录
   `RESEND_FROM_EMAIL`： **noreply@域名**
   `RESEND_API_KEY`：**刚刚复制的 Key**
   ![image-20250906151218330](assets/contributing/image-20250906151218330.png)
+
+## API文档
+
+### OpenAPI文档
+https://docs.open-isle.com
+
+### 部署时间线以及文档时效性
+
+我已经将API Docs的部署融合进本站CI & CD中，目前如下
+
+- 每次合入main之后，都会构建预发环境 http://staging.open-isle.com/ ,现在文档是紧随其后进行部署，也就是说代码合入main之后，如果是新增后台接口，就可以立即通过OpenAPI文档页面进行查看和调试，但是如果想通过OpenAPI调试需要选择预发环境的
+- 每日凌晨三点会构建并重新部署正式环境，届时当日合入main的新后台API也可以通过OpenAPI文档页面调试
+
+![CleanShot 2025-09-10 at 12 .04.48@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/168303009f4047ca828344957e911ff1.png)
+
+👆如图是合入main之后构建预发+docs的情形，总大约耗时4分钟左右
+
+### OpenAPI文档使用
+
+- 预发环境/正式环境切换，可以通过如下位置切换API环境
+
+![CleanShot 2025-09-10 at 12 .08.00@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/f9fb7a0f020d4a0e94159d7820783224.png)
+
+- API分两种，一种是需要鉴权（需登录后的token），另一种是直接访问，可以直接访问的GET请求，直接点击Send即可调试，如下👇，比如本站的推荐流rss: /api/rss: https://docs.open-isle.com/openapi/feed
+
+![CleanShot 2025-09-10 at 12 .09.48@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/2afb42e0c96340559dd42854905ca5fc.png)
+
+- 需要登陆的API，比如关注，取消关注，发帖等，则需要提供token，目前在“API与调试”可获取自身token，可点击link看看👉 https://www.open-isle.com/about?tab=api
+
+![CleanShot 2025-09-10 at 12 .11.07@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/74033f1b9cc14f2fab3cbe3b7fe306d8.png)
+
+copy完token之后，粘贴到Bear之后, 即可发送调试， 如下👇，大家亦可自行尝试：https://docs.open-isle.com/openapi/me
+
+![CleanShot 2025-09-10 at 12 .13.00@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/63913fe2e70541a486651e35c723765e.png)
+
+#### OpenAPI文档应用场景
+
+- 方便大部分前端调试的需求，如果有只想做前端/客户端的同学参与本项目，该平台会大大提高效率
+- 自动化：有自动化发帖/自动化操作的需求，亦可通过该平台实现或调试
+- API文档: https://docs.open-isle.com/openapi

README.md

@@ -4,6 +4,8 @@
   高效的开源社区前后端平台
   <br><br><br>
   <img alt="Image" src="https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/22752cfac5a04a9c90c41995b9f55fed.png" width="1200">
+    <br><br><br>
+  <a href="https://hellogithub.com/repository/nagisa77/OpenIsle" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=8605546658d94cbab45182af2a02e4c8&claim_uid=p5GNFTtZl6HBAYQ" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 </p>
 
 ## 💡 简介

backend/.prettierrc

@@ -0,0 +1,23 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "endOfLine": "lf",
+  "proseWrap": "preserve",
+  "plugins": ["prettier-plugin-java"],
+  "overrides": [
+    {
+      "files": "*.java",
+      "options": {
+        "printWidth": 100,
+        "tabWidth": 2,
+        "semi": true,
+        "singleQuote": false,
+        "trailingComma": "es5"
+      }
+    }
+  ]
+}

backend/src/main/java/com/openisle/OpenIsleApplication.java

@@ -7,6 +7,7 @@ import org.springframework.scheduling.annotation.EnableScheduling;
 @SpringBootApplication
 @EnableScheduling
 public class OpenIsleApplication {
+
   public static void main(String[] args) {
     SpringApplication.run(OpenIsleApplication.class, args);
   }

backend/src/main/java/com/openisle/config/ActivityInitializer.java

@@ -3,15 +3,16 @@ package com.openisle.config;
 import com.openisle.model.Activity;
 import com.openisle.model.ActivityType;
 import com.openisle.repository.ActivityRepository;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
 import lombok.RequiredArgsConstructor;
 import org.springframework.boot.CommandLineRunner;
 import org.springframework.stereotype.Component;
-import java.time.LocalDate;
-import java.time.LocalDateTime;
 
 @Component
 @RequiredArgsConstructor
 public class ActivityInitializer implements CommandLineRunner {
+
   private final ActivityRepository activityRepository;
 
   @Override
@@ -21,7 +22,9 @@ public class ActivityInitializer implements CommandLineRunner {
       a.setTitle("🎡建站送奶茶活动");
       a.setType(ActivityType.MILK_TEA);
       a.setIcon("https://icons.veryicon.com/png/o/food--drinks/delicious-food-1/coffee-36.png");
-            a.setContent("为了有利于建站推广以及激励发布内容，我们推出了建站送奶茶的活动，前50名达到level 1的用户，可以联系站长获取奶茶/咖啡一杯");
+      a.setContent(
+        "为了有利于建站推广以及激励发布内容，我们推出了建站送奶茶的活动，前50名达到level 1的用户，可以联系站长获取奶茶/咖啡一杯"
+      );
       activityRepository.save(a);
     }
 

backend/src/main/java/com/openisle/config/AsyncConfig.java

@@ -1,15 +1,15 @@
 package com.openisle.config;
 
+import java.util.concurrent.Executor;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.scheduling.annotation.EnableAsync;
 import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
 
-import java.util.concurrent.Executor;
-
 @Configuration
 @EnableAsync
 public class AsyncConfig {
+
   @Bean(name = "notificationExecutor")
   public Executor notificationExecutor() {
     ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();

backend/src/main/java/com/openisle/config/CachingConfig.java

@@ -7,6 +7,9 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator;
 import com.fasterxml.jackson.datatype.hibernate6.Hibernate6Module;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import java.time.Duration;
+import java.util.HashMap;
+import java.util.Map;
 import org.springframework.cache.CacheManager;
 import org.springframework.cache.annotation.EnableCaching;
 import org.springframework.context.annotation.Bean;
@@ -21,10 +24,6 @@ import org.springframework.data.redis.serializer.RedisSerializationContext;
 import org.springframework.data.redis.serializer.RedisSerializer;
 import org.springframework.data.redis.serializer.StringRedisSerializer;
 
-import java.time.Duration;
-import java.util.HashMap;
-import java.util.Map;
-
 /**
  * Redis 缓存配置类
  * @author smallclover
@@ -42,12 +41,18 @@ public class CachingConfig {
   public static final String ONLINE_CACHE_NAME = "openisle_online";
   // 注册验证码
   public static final String VERIFY_CACHE_NAME = "openisle_verify";
+  // 发帖频率限制
+  public static final String LIMIT_CACHE_NAME = "openisle_limit";
+  // 用户访问统计
+  public static final String VISIT_CACHE_NAME = "openisle_visit";
+  // 文章缓存
+  public static final String POST_CACHE_NAME = "openisle_posts";
 
   /**
    * 自定义Redis的序列化器
    * @return
    */
-    @Bean()
+  @Bean
   @Primary
   public RedisSerializer<Object> redisSerializer() {
     // 注册 JavaTimeModule 來支持 Java 8 的日期和时间 API,否则回报一下错误，同时还要引入jsr310
@@ -60,8 +65,13 @@ public class CachingConfig {
     objectMapper.registerModule(new JavaTimeModule());
     // Hibernate6Module 可以自动处理懒加载代理对象。
     // Tag对象的creator是FetchType.LAZY
-        objectMapper.registerModule(new Hibernate6Module()
+    objectMapper.registerModule(
-                .disable(Hibernate6Module.Feature.USE_TRANSIENT_ANNOTATION));
+      new Hibernate6Module()
+        .disable(Hibernate6Module.Feature.USE_TRANSIENT_ANNOTATION)
+        // 将 Hibernate 特有的集合类型转换为标准 Java 集合类型
+        // 避免序列化时出现 org.hibernate.collection.spi.PersistentSet 这样的类型信息
+        .configure(Hibernate6Module.Feature.REPLACE_PERSISTENT_COLLECTIONS, true)
+    );
     // service的时候带上类型信息
     // 启用类型信息，避免 LinkedHashMap 问题
     objectMapper.activateDefaultTyping(
@@ -77,19 +87,27 @@ public class CachingConfig {
    * 配置 Spring Cache 使用 RedisCacheManager
    */
   @Bean
-    public CacheManager cacheManager(RedisConnectionFactory connectionFactory, RedisSerializer<Object> redisSerializer) {
+  public CacheManager cacheManager(
-
+    RedisConnectionFactory connectionFactory,
+    RedisSerializer<Object> redisSerializer
+  ) {
     RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
       .entryTtl(Duration.ZERO) // 默认缓存不过期
-                .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
+      .serializeKeysWith(
-                .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(redisSerializer))
+        RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer())
+      )
+      .serializeValuesWith(
+        RedisSerializationContext.SerializationPair.fromSerializer(redisSerializer)
+      )
       .disableCachingNullValues(); // 禁止缓存 null 值
 
     // 个别缓存单独设置 TTL 时间
     Map<String, RedisCacheConfiguration> cacheConfigs = new HashMap<>();
     RedisCacheConfiguration oneHourConfig = config.entryTtl(Duration.ofHours(1));
+    RedisCacheConfiguration tenMinutesConfig = config.entryTtl(Duration.ofMinutes(10));
     cacheConfigs.put(TAG_CACHE_NAME, oneHourConfig);
     cacheConfigs.put(CATEGORY_CACHE_NAME, oneHourConfig);
+    cacheConfigs.put(POST_CACHE_NAME, tenMinutesConfig);
 
     return RedisCacheManager.builder(connectionFactory)
       .cacheDefaults(config)
@@ -101,7 +119,10 @@ public class CachingConfig {
    * 配置 RedisTemplate，支持直接操作 Redis
    */
   @Bean
-    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory,  RedisSerializer<Object> redisSerializer) {
+  public RedisTemplate<String, Object> redisTemplate(
+    RedisConnectionFactory connectionFactory,
+    RedisSerializer<Object> redisSerializer
+  ) {
     RedisTemplate<String, Object> template = new RedisTemplate<>();
     template.setConnectionFactory(connectionFactory);
 

backend/src/main/java/com/openisle/config/ChannelInitializer.java

@@ -9,6 +9,7 @@ import org.springframework.stereotype.Component;
 @Component
 @RequiredArgsConstructor
 public class ChannelInitializer implements CommandLineRunner {
+
   private final MessageConversationRepository conversationRepository;
 
   @Override
@@ -18,14 +19,18 @@ public class ChannelInitializer implements CommandLineRunner {
       chat.setChannel(true);
       chat.setName("吹水群");
       chat.setDescription("吹水聊天");
-            chat.setAvatar("https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/32647273e2334d14adfd4a6ce9db0643.jpeg");
+      chat.setAvatar(
+        "https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/32647273e2334d14adfd4a6ce9db0643.jpeg"
+      );
       conversationRepository.save(chat);
 
       MessageConversation tech = new MessageConversation();
       tech.setChannel(true);
       tech.setName("技术讨论群");
       tech.setDescription("讨论技术相关话题");
-            tech.setAvatar("https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/5edde9a5864e471caa32491dbcdaa8b2.png");
+      tech.setAvatar(
+        "https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/5edde9a5864e471caa32491dbcdaa8b2.png"
+      );
       conversationRepository.save(tech);
     }
   }

backend/src/main/java/com/openisle/config/CustomAccessDeniedHandler.java

@@ -3,21 +3,23 @@ package com.openisle.config;
 import jakarta.servlet.ServletException;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
+import java.io.IOException;
 import org.springframework.security.access.AccessDeniedException;
 import org.springframework.security.web.access.AccessDeniedHandler;
 import org.springframework.stereotype.Component;
 
-import java.io.IOException;
-
 /**
  * Returns 401 Unauthorized when an authenticated user lacks required privileges.
  */
 @Component
 public class CustomAccessDeniedHandler implements AccessDeniedHandler {
+
   @Override
-    public void handle(HttpServletRequest request,
+  public void handle(
+    HttpServletRequest request,
     HttpServletResponse response,
-                       AccessDeniedException accessDeniedException) throws IOException, ServletException {
+    AccessDeniedException accessDeniedException
+  ) throws IOException, ServletException {
     response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
     response.setContentType("application/json");
     response.getWriter().write("{\"error\": \"Unauthorized\"}");

backend/src/main/java/com/openisle/config/OpenApiConfig.java

@@ -5,13 +5,20 @@ import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Info;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
+import io.swagger.v3.oas.models.servers.Server;
+import java.util.List;
+import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
 @Configuration
+@RequiredArgsConstructor
 public class OpenApiConfig {
 
+  private final SpringDocProperties springDocProperties;
+
   @Value("${springdoc.info.title}")
   private String title;
 
@@ -36,13 +43,16 @@ public class OpenApiConfig {
       .in(SecurityScheme.In.HEADER)
       .name(header);
 
+    List<Server> servers = springDocProperties
+      .getServers()
+      .stream()
+      .map(s -> new Server().url(s.getUrl()).description(s.getDescription()))
+      .collect(Collectors.toList());
+
     return new OpenAPI()
-                .info(new Info()
+      .servers(servers)
-					.title(title)
+      .info(new Info().title(title).description(description).version(version))
-					.description(description)
+      .components(new Components().addSecuritySchemes("JWT", securityScheme))
-					.version(version))
-                .components(new Components()
-					.addSecuritySchemes("JWT", securityScheme))
       .addSecurityItem(new SecurityRequirement().addList("JWT"));
   }
 }

backend/src/main/java/com/openisle/config/PointGoodInitializer.java

@@ -10,6 +10,7 @@ import org.springframework.stereotype.Component;
 @Component
 @RequiredArgsConstructor
 public class PointGoodInitializer implements CommandLineRunner {
+
   private final PointGoodRepository pointGoodRepository;
 
   @Override
@@ -18,13 +19,17 @@ public class PointGoodInitializer implements CommandLineRunner {
       PointGood g1 = new PointGood();
       g1.setName("GPT Plus 1 个月");
       g1.setCost(20000);
-            g1.setImage("https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/icons/chatgpt.png");
+      g1.setImage(
+        "https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/icons/chatgpt.png"
+      );
       pointGoodRepository.save(g1);
 
       PointGood g2 = new PointGood();
       g2.setName("奶茶");
       g2.setCost(5000);
-            g2.setImage("https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/icons/coffee.png");
+      g2.setImage(
+        "https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/icons/coffee.png"
+      );
       pointGoodRepository.save(g2);
     }
   }

backend/src/main/java/com/openisle/config/RabbitMQConfig.java

@@ -1,28 +1,29 @@
 package com.openisle.config;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.PostConstruct;
+import java.util.ArrayList;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.amqp.core.Binding;
 import org.springframework.amqp.core.BindingBuilder;
 import org.springframework.amqp.core.Queue;
 import org.springframework.amqp.core.TopicExchange;
 import org.springframework.amqp.rabbit.connection.ConnectionFactory;
+import org.springframework.amqp.rabbit.core.RabbitAdmin;
 import org.springframework.amqp.rabbit.core.RabbitTemplate;
 import org.springframework.amqp.support.converter.Jackson2JsonMessageConverter;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.CommandLineRunner;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import org.springframework.amqp.rabbit.core.RabbitAdmin;
-import org.springframework.boot.CommandLineRunner;
 import org.springframework.context.annotation.DependsOn;
 
-import jakarta.annotation.PostConstruct;
-import java.util.ArrayList;
-import java.util.List;
-
 @Configuration
 @RequiredArgsConstructor
+@Slf4j
 public class RabbitMQConfig {
 
   public static final String EXCHANGE_NAME = "openisle-exchange";
@@ -38,7 +39,7 @@ public class RabbitMQConfig {
 
   @PostConstruct
   public void init() {
-        System.out.println("RabbitMQ配置初始化: 队列数量=" + queueCount + ", 持久化=" + queueDurable);
+    log.info("RabbitMQ配置初始化: 队列数量={}, 持久化={}", queueCount, queueDurable);
   }
 
   @Bean
@@ -51,7 +52,7 @@ public class RabbitMQConfig {
    */
   @Bean
   public List<Queue> shardedQueues() {
-        System.out.println("开始创建分片队列 Bean...");
+    log.info("开始创建分片队列 Bean...");
 
     List<Queue> queues = new ArrayList<>();
     for (int i = 0; i < queueCount; i++) {
@@ -61,7 +62,7 @@ public class RabbitMQConfig {
       queues.add(queue);
     }
 
-        System.out.println("分片队列 Bean 创建完成，总数: " + queues.size());
+    log.info("分片队列 Bean 创建完成，总数: {}", queues.size());
     return queues;
   }
 
@@ -69,8 +70,11 @@ public class RabbitMQConfig {
    * 创建所有分片绑定, 使用十六进制路由键 (notifications.shard.0 - notifications.shard.f)
    */
   @Bean
-    public List<Binding> shardedBindings(TopicExchange exchange, @Qualifier("shardedQueues") List<Queue> shardedQueues) {
+  public List<Binding> shardedBindings(
-        System.out.println("开始创建分片绑定 Bean...");
+    TopicExchange exchange,
+    @Qualifier("shardedQueues") List<Queue> shardedQueues
+  ) {
+    log.info("开始创建分片绑定 Bean...");
     List<Binding> bindings = new ArrayList<>();
     if (shardedQueues != null) {
       for (Queue queue : shardedQueues) {
@@ -82,7 +86,7 @@ public class RabbitMQConfig {
       }
     }
 
-        System.out.println("分片绑定 Bean 创建完成，总数: " + bindings.size());
+    log.info("分片绑定 Bean 创建完成，总数: {}", bindings.size());
     return bindings;
   }
 
@@ -106,7 +110,9 @@ public class RabbitMQConfig {
   public Jackson2JsonMessageConverter messageConverter() {
     ObjectMapper objectMapper = new ObjectMapper();
     objectMapper.registerModule(new com.fasterxml.jackson.datatype.jsr310.JavaTimeModule());
-        objectMapper.disable(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+    objectMapper.disable(
+      com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS
+    );
     return new Jackson2JsonMessageConverter(objectMapper);
   }
 
@@ -128,21 +134,23 @@ public class RabbitMQConfig {
    */
   @Bean
   @DependsOn({ "rabbitAdmin", "shardedQueues", "exchange" })
-    public CommandLineRunner queueDeclarationRunner(RabbitAdmin rabbitAdmin,
+  public CommandLineRunner queueDeclarationRunner(
+    RabbitAdmin rabbitAdmin,
     @Qualifier("shardedQueues") List<Queue> shardedQueues,
     TopicExchange exchange,
     Queue legacyQueue,
     @Qualifier("shardedBindings") List<Binding> shardedBindings,
-                                                   Binding legacyBinding) {
+    Binding legacyBinding
+  ) {
     return args -> {
-            System.out.println("=== 开始主动声明 RabbitMQ 组件 ===");
+      log.info("=== 开始主动声明 RabbitMQ 组件 ===");
 
       try {
         // 声明交换
         rabbitAdmin.declareExchange(exchange);
 
         // 声明分片队列 - 检查存在性
-                System.out.println("开始检查并声明 " + shardedQueues.size() + " 个分片队列...");
+        log.info("开始检查并声明 {} 个分片队列...", shardedQueues.size());
         int successCount = 0;
         int skippedCount = 0;
 
@@ -155,49 +163,56 @@ public class RabbitMQConfig {
             rabbitAdmin.declareQueue(queue);
             successCount++;
           } catch (org.springframework.amqp.AmqpIOException e) {
-                        if (e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")) {
+            if (
+              e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")
+            ) {
               skippedCount++;
             }
           } catch (Exception e) {
-                        System.err.println("队列声明失败: " + queueName + ", 错误: " + e.getMessage());
+            log.error("队列声明失败: {}, 错误: {}", queueName, e.getMessage());
           }
         }
-                System.out.println("分片队列处理完成: 成功 " + successCount + ", 跳过 " + skippedCount + ", 总数 " + shardedQueues.size());
+        log.info(
+          "分片队列处理完成: 成功 {}, 跳过 {}, 总数 {}",
+          successCount,
+          skippedCount,
+          shardedQueues.size()
+        );
 
         // 声明分片绑定
-                System.out.println("开始声明 " + shardedBindings.size() + " 个分片绑定...");
+        log.info("开始声明 {} 个分片绑定...", shardedBindings.size());
         int bindingSuccessCount = 0;
         for (Binding binding : shardedBindings) {
           try {
             rabbitAdmin.declareBinding(binding);
             bindingSuccessCount++;
           } catch (Exception e) {
-                        System.err.println("绑定声明失败: " + e.getMessage());
+            log.error("绑定声明失败: {}", e.getMessage());
           }
         }
-                System.out.println("分片绑定声明完成: 成功 " + bindingSuccessCount + "/" + shardedBindings.size());
+        log.info("分片绑定声明完成: 成功 {}/{}", bindingSuccessCount, shardedBindings.size());
 
         // 声明遗留队列和绑定 - 检查存在性
         try {
           rabbitAdmin.declareQueue(legacyQueue);
           rabbitAdmin.declareBinding(legacyBinding);
-                    System.out.println("遗留队列和绑定就绪: " + QUEUE_NAME + " (已存在或新创建)");
+          log.info("遗留队列和绑定就绪: {} (已存在或新创建)", QUEUE_NAME);
         } catch (org.springframework.amqp.AmqpIOException e) {
-                    if (e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")) {
+          if (
-                        System.out.println("遗留队列已存在但 durable 设置不匹配: " + QUEUE_NAME + ", 保持现有队列");
+            e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")
+          ) {
+            log.warn("遗留队列已存在但 durable 设置不匹配: {}, 保持现有队列", QUEUE_NAME);
           } else {
-                        System.err.println("遗留队列声明失败: " + QUEUE_NAME + ", 错误: " + e.getMessage());
+            log.error("遗留队列声明失败: {}, 错误: {}", QUEUE_NAME, e.getMessage());
           }
         } catch (Exception e) {
-                    System.err.println("遗留队列声明失败: " + QUEUE_NAME + ", 错误: " + e.getMessage());
+          log.error("遗留队列声明失败: {}, 错误: {}", QUEUE_NAME, e.getMessage());
         }
 
-                System.out.println("=== RabbitMQ 组件声明完成 ===");
+        log.info("=== RabbitMQ 组件声明完成 ===");
-                System.out.println("请检查 RabbitMQ 管理界面确认队列已正确创建");
+        log.info("请检查 RabbitMQ 管理界面确认队列已正确创建");
-                
       } catch (Exception e) {
-                System.err.println("RabbitMQ 组件声明过程中发生严重错误:");
+        log.error("RabbitMQ 组件声明过程中发生严重错误", e);
-                e.printStackTrace();
       }
     };
   }

backend/src/main/java/com/openisle/config/SchedulerConfig.java

@@ -2,13 +2,14 @@ package com.openisle.config;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.TaskScheduler;
 import org.springframework.scheduling.annotation.EnableScheduling;
 import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;
-import org.springframework.scheduling.TaskScheduler;
 
 @Configuration
 @EnableScheduling
 public class SchedulerConfig {
+
   @Bean
   public TaskScheduler taskScheduler() {
     ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();

backend/src/main/java/com/openisle/config/SecurityConfig.java

@@ -1,11 +1,20 @@
 package com.openisle.config;
 
+import com.openisle.repository.UserRepository;
 import com.openisle.service.JwtService;
 import com.openisle.service.UserVisitService;
-import com.openisle.repository.UserRepository;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.time.LocalDate;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.http.HttpMethod;
 import org.springframework.security.authentication.AuthenticationManager;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
@@ -21,29 +30,25 @@ import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.security.web.SecurityFilterChain;
 import org.springframework.security.web.access.AccessDeniedHandler;
 import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
-import org.springframework.web.filter.OncePerRequestFilter;
 import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.cors.CorsConfigurationSource;
 import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
-import org.springframework.beans.factory.annotation.Value;
+import org.springframework.web.filter.OncePerRequestFilter;
-import java.util.List;
-
-import jakarta.servlet.FilterChain;
-import jakarta.servlet.ServletException;
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
-import java.io.IOException;
 
 @Configuration
 @RequiredArgsConstructor
 public class SecurityConfig {
+
   private final JwtService jwtService;
   private final UserRepository userRepository;
   private final AccessDeniedHandler customAccessDeniedHandler;
   private final UserVisitService userVisitService;
+
   @Value("${app.website-url}")
   private String websiteUrl;
 
+  private final RedisTemplate redisTemplate;
+
   @Bean
   public PasswordEncoder passwordEncoder() {
     return new BCryptPasswordEncoder();
@@ -51,18 +56,26 @@ public class SecurityConfig {
 
   @Bean
   public UserDetailsService userDetailsService() {
-        return username -> userRepository.findByUsername(username)
+    return username ->
-                .<UserDetails>map(user -> org.springframework.security.core.userdetails.User
+      userRepository
-                        .withUsername(user.getUsername())
+        .findByUsername(username)
+        .<UserDetails>map(user ->
+          org.springframework.security.core.userdetails.User.withUsername(user.getUsername())
             .password(user.getPassword())
             .authorities(user.getRole().name())
-                        .build())
+            .build()
+        )
         .orElseThrow(() -> new UsernameNotFoundException("User not found"));
   }
 
   @Bean
-    public AuthenticationManager authenticationManager(HttpSecurity http, PasswordEncoder passwordEncoder, UserDetailsService userDetailsService) throws Exception {
+  public AuthenticationManager authenticationManager(
-        return http.getSharedObject(AuthenticationManagerBuilder.class)
+    HttpSecurity http,
+    PasswordEncoder passwordEncoder,
+    UserDetailsService userDetailsService
+  ) throws Exception {
+    return http
+      .getSharedObject(AuthenticationManagerBuilder.class)
       .userDetailsService(userDetailsService)
       .passwordEncoder(passwordEncoder)
       .and()
@@ -72,7 +85,8 @@ public class SecurityConfig {
   @Bean
   public CorsConfigurationSource corsConfigurationSource() {
     CorsConfiguration cfg = new CorsConfiguration();
-        cfg.setAllowedOrigins(List.of(
+    cfg.setAllowedOrigins(
+      List.of(
         "http://127.0.0.1:8080",
         "http://127.0.0.1:8081",
         "http://127.0.0.1:8082",
@@ -90,9 +104,13 @@ public class SecurityConfig {
         "http://192.168.7.98",
         "http://192.168.7.98:3000",
         "https://petstore.swagger.io",
+        // 允许自建OpenAPI地址
+        "https://docs.open-isle.com",
+        "https://www.docs.open-isle.com",
         websiteUrl,
         websiteUrl.replace("://www.", "://")
-        ));
+      )
+    );
     cfg.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
     cfg.setAllowedHeaders(List.of("*"));
     cfg.setAllowCredentials(true);
@@ -103,43 +121,76 @@ public class SecurityConfig {
 
   @Bean
   public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
-        http.csrf(csrf -> csrf.disable())
+    http
+      .csrf(csrf -> csrf.disable())
       .cors(Customizer.withDefaults())
       .headers(h -> h.frameOptions(f -> f.sameOrigin()))
       .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
       .exceptionHandling(eh -> eh.accessDeniedHandler(customAccessDeniedHandler))
-            .authorizeHttpRequests(auth -> auth
+      .authorizeHttpRequests(auth ->
-                    .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
+        auth
-                    .requestMatchers("/api/ws/**", "/api/sockjs/**").permitAll()
+          .requestMatchers(HttpMethod.OPTIONS, "/**")
-                    .requestMatchers("/api/v3/api-docs/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.POST, "/api/auth/**").permitAll()
+          .requestMatchers("/api/ws/**", "/api/sockjs/**")
-                    .requestMatchers(HttpMethod.GET, "/api/posts/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/comments/**").permitAll()
+          .requestMatchers("/api/v3/api-docs/**")
-                    .requestMatchers(HttpMethod.GET, "/api/categories/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/tags/**").permitAll()
+          .requestMatchers(HttpMethod.POST, "/api/auth/**")
-                    .requestMatchers(HttpMethod.GET, "/api/config/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.POST,"/api/auth/google").permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/posts/**")
-                    .requestMatchers(HttpMethod.POST,"/api/auth/reason").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/search/**").permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/comments/**")
-                    .requestMatchers(HttpMethod.GET, "/api/users/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/medals/**").permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/categories/**")
-                    .requestMatchers(HttpMethod.GET, "/api/push/public-key").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/reaction-types").permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/tags/**")
-                    .requestMatchers(HttpMethod.GET, "/api/activities/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/sitemap.xml").permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/config/**")
-                    .requestMatchers(HttpMethod.GET, "/api/channels").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.GET, "/api/rss").permitAll()
+          .requestMatchers(HttpMethod.POST, "/api/auth/google")
-                    .requestMatchers(HttpMethod.GET, "/api/online/**").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.POST, "/api/online/**").permitAll()
+          .requestMatchers(HttpMethod.POST, "/api/auth/reason")
-                    .requestMatchers(HttpMethod.GET, "/api/point-goods").permitAll()
+          .permitAll()
-                    .requestMatchers(HttpMethod.POST, "/api/point-goods").permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/search/**")
-                    .requestMatchers(HttpMethod.POST, "/api/categories/**").hasAuthority("ADMIN")
+          .permitAll()
-                    .requestMatchers(HttpMethod.POST, "/api/tags/**").authenticated()
+          .requestMatchers(HttpMethod.GET, "/api/users/**")
-                    .requestMatchers(HttpMethod.DELETE, "/api/categories/**").hasAuthority("ADMIN")
+          .permitAll()
-                    .requestMatchers(HttpMethod.DELETE, "/api/tags/**").hasAuthority("ADMIN")
+          .requestMatchers(HttpMethod.GET, "/api/medals/**")
-                    .requestMatchers(HttpMethod.GET, "/api/stats/**").hasAuthority("ADMIN")
+          .permitAll()
-                    .requestMatchers("/api/admin/**").hasAuthority("ADMIN")
+          .requestMatchers(HttpMethod.GET, "/api/push/public-key")
-                    .anyRequest().authenticated()
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/reaction-types")
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/activities/**")
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/sitemap.xml")
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/channels")
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/rss")
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/online/**")
+          .permitAll()
+          .requestMatchers(HttpMethod.POST, "/api/online/**")
+          .permitAll()
+          .requestMatchers(HttpMethod.GET, "/api/point-goods")
+          .permitAll()
+          .requestMatchers(HttpMethod.POST, "/api/point-goods")
+          .permitAll()
+          .requestMatchers(HttpMethod.POST, "/api/categories/**")
+          .hasAuthority("ADMIN")
+          .requestMatchers(HttpMethod.POST, "/api/tags/**")
+          .authenticated()
+          .requestMatchers(HttpMethod.DELETE, "/api/categories/**")
+          .hasAuthority("ADMIN")
+          .requestMatchers(HttpMethod.DELETE, "/api/tags/**")
+          .hasAuthority("ADMIN")
+          .requestMatchers(HttpMethod.GET, "/api/stats/**")
+          .hasAuthority("ADMIN")
+          .requestMatchers("/api/admin/**")
+          .hasAuthority("ADMIN")
+          .anyRequest()
+          .authenticated()
       )
       .addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class)
       .addFilterAfter(userVisitFilter(), UsernamePasswordAuthenticationFilter.class);
@@ -150,7 +201,11 @@ public class SecurityConfig {
   public OncePerRequestFilter jwtAuthenticationFilter() {
     return new OncePerRequestFilter() {
       @Override
-            protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
+      protected void doFilterInternal(
+        HttpServletRequest request,
+        HttpServletResponse response,
+        FilterChain filterChain
+      ) throws ServletException, IOException {
         // 让预检请求直接通过
         if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
           filterChain.doFilter(request, response);
@@ -159,14 +214,22 @@ public class SecurityConfig {
         String authHeader = request.getHeader("Authorization");
         String uri = request.getRequestURI();
 
-                boolean publicGet = "GET".equalsIgnoreCase(request.getMethod()) &&
+        boolean publicGet =
-                        (uri.startsWith("/api/posts") || uri.startsWith("/api/comments") ||
+          "GET".equalsIgnoreCase(request.getMethod()) &&
-                         uri.startsWith("/api/categories") || uri.startsWith("/api/tags") ||
+          (uri.startsWith("/api/posts") ||
-                        uri.startsWith("/api/search") || uri.startsWith("/api/users") ||
+            uri.startsWith("/api/comments") ||
-                         uri.startsWith("/api/reaction-types") || uri.startsWith("/api/config") ||
+            uri.startsWith("/api/categories") ||
-                         uri.startsWith("/api/activities") || uri.startsWith("/api/push/public-key") ||
+            uri.startsWith("/api/tags") ||
-                                uri.startsWith("/api/point-goods") || uri.startsWith("/api/channels") ||
+            uri.startsWith("/api/search") ||
-                         uri.startsWith("/api/sitemap.xml") || uri.startsWith("/api/medals") ||
+            uri.startsWith("/api/users") ||
+            uri.startsWith("/api/reaction-types") ||
+            uri.startsWith("/api/config") ||
+            uri.startsWith("/api/activities") ||
+            uri.startsWith("/api/push/public-key") ||
+            uri.startsWith("/api/point-goods") ||
+            uri.startsWith("/api/channels") ||
+            uri.startsWith("/api/sitemap.xml") ||
+            uri.startsWith("/api/medals") ||
             uri.startsWith("/api/rss"));
 
         if (authHeader != null && authHeader.startsWith("Bearer ")) {
@@ -175,18 +238,27 @@ public class SecurityConfig {
             String username = jwtService.validateAndGetSubject(token);
             UserDetails userDetails = userDetailsService().loadUserByUsername(username);
             UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
-                                userDetails, null, userDetails.getAuthorities());
+              userDetails,
-                        org.springframework.security.core.context.SecurityContextHolder.getContext().setAuthentication(authToken);
+              null,
+              userDetails.getAuthorities()
+            );
+            org.springframework.security.core.context.SecurityContextHolder.getContext().setAuthentication(
+              authToken
+            );
           } catch (Exception e) {
             response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
             response.setContentType("application/json");
             response.getWriter().write("{\"error\": \"Invalid or expired token\"}");
             return;
           }
-                } else if (!uri.startsWith("/api/auth") && !publicGet
+        } else if (
-                        && !uri.startsWith("/api/ws") && !uri.startsWith("/api/sockjs")
+          !uri.startsWith("/api/auth") &&
-                        && !uri.startsWith("/api/v3/api-docs")
+          !publicGet &&
-                        && !uri.startsWith("/api/online")) {
+          !uri.startsWith("/api/ws") &&
+          !uri.startsWith("/api/sockjs") &&
+          !uri.startsWith("/api/v3/api-docs") &&
+          !uri.startsWith("/api/online")
+        ) {
           response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
           response.setContentType("application/json");
           response.getWriter().write("{\"error\": \"Missing token\"}");
@@ -202,10 +274,21 @@ public class SecurityConfig {
   public OncePerRequestFilter userVisitFilter() {
     return new OncePerRequestFilter() {
       @Override
-            protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
+      protected void doFilterInternal(
-                var auth = org.springframework.security.core.context.SecurityContextHolder.getContext().getAuthentication();
+        HttpServletRequest request,
-                if (auth != null && auth.isAuthenticated() && !(auth instanceof org.springframework.security.authentication.AnonymousAuthenticationToken)) {
+        HttpServletResponse response,
-                    userVisitService.recordVisit(auth.getName());
+        FilterChain filterChain
+      ) throws ServletException, IOException {
+        var auth =
+          org.springframework.security.core.context.SecurityContextHolder.getContext().getAuthentication();
+        if (
+          auth != null &&
+          auth.isAuthenticated() &&
+          !(auth instanceof
+              org.springframework.security.authentication.AnonymousAuthenticationToken)
+        ) {
+          String key = CachingConfig.VISIT_CACHE_NAME + ":" + LocalDate.now();
+          redisTemplate.opsForSet().add(key, auth.getName());
         }
         filterChain.doFilter(request, response);
       }

backend/src/main/java/com/openisle/config/ShardInfo.java

@@ -8,6 +8,7 @@ import lombok.NoArgsConstructor;
 @AllArgsConstructor
 @NoArgsConstructor
 public class ShardInfo {
+
   private int shardIndex;
   private String queueName;
   private String routingKey;

backend/src/main/java/com/openisle/config/ShardingStrategy.java

@@ -1,14 +1,13 @@
 package com.openisle.config;
 
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.stream.Collectors;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
 
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicLong;
-import java.util.Map;
-import java.util.stream.Collectors;
-
 @Component
 @Slf4j
 public class ShardingStrategy {
@@ -38,8 +37,13 @@ public class ShardingStrategy {
     int shard = getShardFromHexChar(firstChar);
     recordShardUsage(shard);
 
-        log.debug("Username '{}' -> hash '{}' -> firstChar '{}' -> shard {}", 
+    log.debug(
-                 username, hash, firstChar, shard);
+      "Username '{}' -> hash '{}' -> firstChar '{}' -> shard {}",
+      username,
+      hash,
+      firstChar,
+      shard
+    );
 
     return getShardInfoByIndex(shard);
   }
@@ -80,5 +84,4 @@ public class ShardingStrategy {
   private void recordShardUsage(int shard) {
     shardCounts.computeIfAbsent(shard, k -> new AtomicLong(0)).incrementAndGet();
   }
-
 }

backend/src/main/java/com/openisle/config/SpringDocProperties.java

@@ -0,0 +1,22 @@
+package com.openisle.config;
+
+import java.util.ArrayList;
+import java.util.List;
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Data
+@Component
+@ConfigurationProperties(prefix = "springdoc.api-docs")
+public class SpringDocProperties {
+
+  private List<ServerConfig> servers = new ArrayList<>();
+
+  @Data
+  public static class ServerConfig {
+
+    private String url;
+    private String description;
+  }
+}

backend/src/main/java/com/openisle/config/SystemUserInitializer.java

@@ -14,12 +14,15 @@ import org.springframework.stereotype.Component;
 @Component
 @RequiredArgsConstructor
 public class SystemUserInitializer implements CommandLineRunner {
+
   private final UserRepository userRepository;
   private final PasswordEncoder passwordEncoder;
 
   @Override
   public void run(String... args) {
-        userRepository.findByUsername("system").orElseGet(() -> {
+    userRepository
+      .findByUsername("system")
+      .orElseGet(() -> {
         User system = new User();
         system.setUsername("system");
         system.setEmail("system@openisle.local");
@@ -28,9 +31,10 @@ public class SystemUserInitializer implements CommandLineRunner {
         system.setRole(Role.USER);
         system.setVerified(true);
         system.setApproved(true);
-            system.setAvatar("https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/image.png");
+        system.setAvatar(
+          "https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/image.png"
+        );
         return userRepository.save(system);
       });
   }
 }
-

backend/src/main/java/com/openisle/controller/ActivityController.java

@@ -9,29 +9,45 @@ import com.openisle.model.ActivityType;
 import com.openisle.model.User;
 import com.openisle.service.ActivityService;
 import com.openisle.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
 @RestController
 @RequestMapping("/api/activities")
 @RequiredArgsConstructor
 public class ActivityController {
+
   private final ActivityService activityService;
   private final UserService userService;
   private final ActivityMapper activityMapper;
 
   @GetMapping
+  @Operation(summary = "List activities", description = "Retrieve all activities")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of activities",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = ActivityDto.class)))
+  )
   public List<ActivityDto> list() {
-        return activityService.list().stream()
+    return activityService.list().stream().map(activityMapper::toDto).collect(Collectors.toList());
-                .map(activityMapper::toDto)
-                .collect(Collectors.toList());
   }
 
   @GetMapping("/milk-tea")
+  @Operation(summary = "Milk tea info", description = "Get milk tea activity information")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Milk tea info",
+    content = @Content(schema = @Schema(implementation = MilkTeaInfoDto.class))
+  )
   public MilkTeaInfoDto milkTea() {
     Activity a = activityService.getByType(ActivityType.MILK_TEA);
     long count = activityService.countParticipants(a);
@@ -45,7 +61,17 @@ public class ActivityController {
   }
 
   @PostMapping("/milk-tea/redeem")
-    public java.util.Map<String, String> redeemMilkTea(@RequestBody MilkTeaRedeemRequest req, Authentication auth) {
+  @Operation(summary = "Redeem milk tea", description = "Redeem milk tea activity reward")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Redeem result",
+    content = @Content(schema = @Schema(implementation = java.util.Map.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public java.util.Map<String, String> redeemMilkTea(
+    @RequestBody MilkTeaRedeemRequest req,
+    Authentication auth
+  ) {
     User user = userService.findByIdentifier(auth.getName()).orElseThrow();
     Activity a = activityService.getByType(ActivityType.MILK_TEA);
     boolean first = activityService.redeem(a, user, req.getContact());

backend/src/main/java/com/openisle/controller/AdminCommentController.java

@@ -3,6 +3,11 @@ package com.openisle.controller;
 import com.openisle.dto.CommentDto;
 import com.openisle.mapper.CommentMapper;
 import com.openisle.service.CommentService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
@@ -14,15 +19,30 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api/admin/comments")
 @RequiredArgsConstructor
 public class AdminCommentController {
+
   private final CommentService commentService;
   private final CommentMapper commentMapper;
 
   @PostMapping("/{id}/pin")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Pin comment", description = "Pin a comment by its id")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Pinned comment",
+    content = @Content(schema = @Schema(implementation = CommentDto.class))
+  )
   public CommentDto pin(@PathVariable Long id, Authentication auth) {
     return commentMapper.toDto(commentService.pinComment(auth.getName(), id));
   }
 
   @PostMapping("/{id}/unpin")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Unpin comment", description = "Remove pin from a comment")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unpinned comment",
+    content = @Content(schema = @Schema(implementation = CommentDto.class))
+  )
   public CommentDto unpin(@PathVariable Long id, Authentication auth) {
     return commentMapper.toDto(commentService.unpinComment(auth.getName(), id));
   }

backend/src/main/java/com/openisle/controller/AdminConfigController.java

@@ -5,6 +5,11 @@ import com.openisle.service.AiUsageService;
 import com.openisle.service.PasswordValidator;
 import com.openisle.service.PostService;
 import com.openisle.service.RegisterModeService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
@@ -12,12 +17,23 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api/admin/config")
 @RequiredArgsConstructor
 public class AdminConfigController {
+
   private final PostService postService;
   private final PasswordValidator passwordValidator;
   private final AiUsageService aiUsageService;
   private final RegisterModeService registerModeService;
 
   @GetMapping
+  @SecurityRequirement(name = "JWT")
+  @Operation(
+    summary = "Get configuration",
+    description = "Retrieve application configuration settings"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Current configuration",
+    content = @Content(schema = @Schema(implementation = ConfigDto.class))
+  )
   public ConfigDto getConfig() {
     ConfigDto dto = new ConfigDto();
     dto.setPublishMode(postService.getPublishMode());
@@ -28,6 +44,16 @@ public class AdminConfigController {
   }
 
   @PostMapping
+  @SecurityRequirement(name = "JWT")
+  @Operation(
+    summary = "Update configuration",
+    description = "Update application configuration settings"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Updated configuration",
+    content = @Content(schema = @Schema(implementation = ConfigDto.class))
+  )
   public ConfigDto updateConfig(@RequestBody ConfigDto dto) {
     if (dto.getPublishMode() != null) {
       postService.setPublishMode(dto.getPublishMode());
@@ -43,5 +69,4 @@ public class AdminConfigController {
     }
     return getConfig();
   }
-
 }

backend/src/main/java/com/openisle/controller/AdminController.java

@@ -1,15 +1,28 @@
 package com.openisle.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.Map;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
-import java.util.Map;
 
 /**
  * Simple admin demo endpoint.
  */
 @RestController
 public class AdminController {
+
   @GetMapping("/api/admin/hello")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Admin greeting", description = "Returns a greeting for admin users")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Greeting payload",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public Map<String, String> adminHello() {
     return Map.of("message", "Hello, Admin User");
   }

backend/src/main/java/com/openisle/controller/AdminPostController.java

@@ -3,11 +3,16 @@ package com.openisle.controller;
 import com.openisle.dto.PostSummaryDto;
 import com.openisle.mapper.PostMapper;
 import com.openisle.service.PostService;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
-
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import java.util.List;
 import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
 
 /**
  * Endpoints for administrators to manage posts.
@@ -16,43 +21,109 @@ import java.util.stream.Collectors;
 @RequestMapping("/api/admin/posts")
 @RequiredArgsConstructor
 public class AdminPostController {
+
   private final PostService postService;
   private final PostMapper postMapper;
 
   @GetMapping("/pending")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "List pending posts", description = "Retrieve posts awaiting approval")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Pending posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
   public List<PostSummaryDto> pendingPosts() {
-        return postService.listPendingPosts().stream()
+    return postService
+      .listPendingPosts()
+      .stream()
       .map(postMapper::toSummaryDto)
       .collect(Collectors.toList());
   }
 
   @PostMapping("/{id}/approve")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Approve post", description = "Approve a pending post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Approved post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
   public PostSummaryDto approve(@PathVariable Long id) {
     return postMapper.toSummaryDto(postService.approvePost(id));
   }
 
   @PostMapping("/{id}/reject")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Reject post", description = "Reject a pending post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Rejected post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
   public PostSummaryDto reject(@PathVariable Long id) {
     return postMapper.toSummaryDto(postService.rejectPost(id));
   }
 
   @PostMapping("/{id}/pin")
-    public PostSummaryDto pin(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Pin post", description = "Pin a post to the top")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Pinned post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
+  public PostSummaryDto pin(
+    @PathVariable Long id,
+    org.springframework.security.core.Authentication auth
+  ) {
     return postMapper.toSummaryDto(postService.pinPost(id, auth.getName()));
   }
 
   @PostMapping("/{id}/unpin")
-    public PostSummaryDto unpin(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Unpin post", description = "Remove a post from the top")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unpinned post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
+  public PostSummaryDto unpin(
+    @PathVariable Long id,
+    org.springframework.security.core.Authentication auth
+  ) {
     return postMapper.toSummaryDto(postService.unpinPost(id, auth.getName()));
   }
 
   @PostMapping("/{id}/rss-exclude")
-    public PostSummaryDto excludeFromRss(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Exclude from RSS", description = "Exclude a post from RSS feed")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Updated post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
+  public PostSummaryDto excludeFromRss(
+    @PathVariable Long id,
+    org.springframework.security.core.Authentication auth
+  ) {
     return postMapper.toSummaryDto(postService.excludeFromRss(id, auth.getName()));
   }
 
   @PostMapping("/{id}/rss-include")
-    public PostSummaryDto includeInRss(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Include in RSS", description = "Include a post in the RSS feed")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Updated post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
+  public PostSummaryDto includeInRss(
+    @PathVariable Long id,
+    org.springframework.security.core.Authentication auth
+  ) {
     return postMapper.toSummaryDto(postService.includeInRss(id, auth.getName()));
   }
 }

backend/src/main/java/com/openisle/controller/AdminTagController.java

@@ -5,28 +5,50 @@ import com.openisle.mapper.TagMapper;
 import com.openisle.model.Tag;
 import com.openisle.service.PostService;
 import com.openisle.service.TagService;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
-
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import java.util.List;
 import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/api/admin/tags")
 @RequiredArgsConstructor
 public class AdminTagController {
+
   private final TagService tagService;
   private final PostService postService;
   private final TagMapper tagMapper;
 
   @GetMapping("/pending")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "List pending tags", description = "Retrieve tags awaiting approval")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Pending tags",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class)))
+  )
   public List<TagDto> pendingTags() {
-        return tagService.listPendingTags().stream()
+    return tagService
+      .listPendingTags()
+      .stream()
       .map(t -> tagMapper.toDto(t, postService.countPostsByTag(t.getId())))
       .collect(Collectors.toList());
   }
 
   @PostMapping("/{id}/approve")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Approve tag", description = "Approve a pending tag")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Approved tag",
+    content = @Content(schema = @Schema(implementation = TagDto.class))
+  )
   public TagDto approve(@PathVariable Long id) {
     Tag tag = tagService.approveTag(id);
     long count = postService.countPostsByTag(tag.getId());

backend/src/main/java/com/openisle/controller/AdminUserController.java

@@ -3,9 +3,12 @@ package com.openisle.controller;
 import com.openisle.model.Notification;
 import com.openisle.model.NotificationType;
 import com.openisle.model.User;
-import com.openisle.service.EmailSender;
 import com.openisle.repository.NotificationRepository;
 import com.openisle.repository.UserRepository;
+import com.openisle.service.EmailSender;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
@@ -15,37 +18,53 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api/admin/users")
 @RequiredArgsConstructor
 public class AdminUserController {
+
   private final UserRepository userRepository;
   private final NotificationRepository notificationRepository;
   private final EmailSender emailSender;
+
   @Value("${app.website-url}")
   private String websiteUrl;
 
   @PostMapping("/{id}/approve")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Approve user", description = "Approve a pending user registration")
+  @ApiResponse(responseCode = "200", description = "User approved")
   public ResponseEntity<?> approve(@PathVariable Long id) {
     User user = userRepository.findById(id).orElseThrow();
     user.setApproved(true);
     userRepository.save(user);
     markRegisterRequestNotificationsRead(user);
-        emailSender.sendEmail(user.getEmail(), "您的注册已审核通过",
+    emailSender.sendEmail(
-                "🎉您的注册已经审核通过, 点击以访问网站: " + websiteUrl);
+      user.getEmail(),
+      "您的注册已审核通过",
+      "🎉您的注册已经审核通过, 点击以访问网站: " + websiteUrl
+    );
     return ResponseEntity.ok().build();
   }
 
   @PostMapping("/{id}/reject")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Reject user", description = "Reject a pending user registration")
+  @ApiResponse(responseCode = "200", description = "User rejected")
   public ResponseEntity<?> reject(@PathVariable Long id) {
     User user = userRepository.findById(id).orElseThrow();
     user.setApproved(false);
     userRepository.save(user);
     markRegisterRequestNotificationsRead(user);
-        emailSender.sendEmail(user.getEmail(), "您的注册已被管理员拒绝",
+    emailSender.sendEmail(
-                "您的注册被管理员拒绝, 点击链接可以重新填写理由申请: " + websiteUrl);
+      user.getEmail(),
+      "您的注册已被管理员拒绝",
+      "您的注册被管理员拒绝, 点击链接可以重新填写理由申请: " + websiteUrl
+    );
     return ResponseEntity.ok().build();
   }
 
   private void markRegisterRequestNotificationsRead(User applicant) {
-        java.util.List<Notification> notifs =
+    java.util.List<Notification> notifs = notificationRepository.findByTypeAndFromUser(
-                notificationRepository.findByTypeAndFromUser(NotificationType.REGISTER_REQUEST, applicant);
+      NotificationType.REGISTER_REQUEST,
+      applicant
+    );
     for (Notification n : notifs) {
       n.setRead(true);
     }

backend/src/main/java/com/openisle/controller/AiController.java

@@ -1,7 +1,13 @@
 package com.openisle.controller;
 
-import com.openisle.service.OpenAiService;
 import com.openisle.service.AiUsageService;
+import com.openisle.service.OpenAiService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.Map;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
@@ -10,8 +16,6 @@ import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
-import java.util.Map;
-
 @RestController
 @RequestMapping("/api/ai")
 @RequiredArgsConstructor
@@ -21,8 +25,17 @@ public class AiController {
   private final AiUsageService aiUsageService;
 
   @PostMapping("/format")
-    public ResponseEntity<Map<String, String>> format(@RequestBody Map<String, String> req,
+  @Operation(summary = "Format markdown", description = "Format text via AI")
-                                                     Authentication auth) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Formatted content",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<Map<String, String>> format(
+    @RequestBody Map<String, String> req,
+    Authentication auth
+  ) {
     String text = req.get("text");
     if (text == null) {
       return ResponseEntity.badRequest().build();
@@ -33,7 +46,8 @@ public class AiController {
       return ResponseEntity.status(429).build();
     }
     aiUsageService.incrementAndGetCount(auth.getName());
-        return openAiService.formatMarkdown(text)
+    return openAiService
+      .formatMarkdown(text)
       .map(t -> ResponseEntity.ok(Map.of("content", t)))
       .orElse(ResponseEntity.status(500).build());
   }

backend/src/main/java/com/openisle/controller/AuthController.java

@@ -8,20 +8,25 @@ import com.openisle.model.User;
 import com.openisle.repository.UserRepository;
 import com.openisle.service.*;
 import com.openisle.util.VerifyType;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.TimeUnit;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.Map;
-import java.util.Optional;
-import java.util.concurrent.TimeUnit;
-
 @RestController
 @RequestMapping("/api/auth")
 @RequiredArgsConstructor
 public class AuthController {
+
   private final UserService userService;
   private final JwtService jwtService;
   private final EmailSender emailService;
@@ -36,7 +41,6 @@ public class AuthController {
   private final UserRepository userRepository;
   private final InviteService inviteService;
 
-
   @Value("${app.captcha.enabled:false}")
   private boolean captchaEnabled;
 
@@ -47,6 +51,12 @@ public class AuthController {
   private boolean loginCaptchaEnabled;
 
   @PostMapping("/register")
+  @Operation(summary = "Register user", description = "Register a new user account")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Registration result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> register(@RequestBody RegisterRequest req) {
     if (captchaEnabled && registerCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid captcha"));
@@ -58,23 +68,34 @@ public class AuthController {
       }
       try {
         User user = userService.registerWithInvite(
-                        req.getUsername(), req.getEmail(), req.getPassword());
+          req.getUsername(),
+          req.getEmail(),
+          req.getPassword()
+        );
         inviteService.consume(req.getInviteToken(), user.getUsername());
         // 发送确认邮件
         userService.sendVerifyMail(user, VerifyType.REGISTER);
-                return ResponseEntity.ok(Map.of(
+        return ResponseEntity.ok(
-                        "token", jwtService.generateToken(user.getUsername()),
+          Map.of(
-                        "reason_code", "INVITE_APPROVED"
+            "token",
-                ));
+            jwtService.generateToken(user.getUsername()),
+            "reason_code",
+            "INVITE_APPROVED"
+          )
+        );
       } catch (FieldException e) {
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "field", e.getField(),
+          Map.of("field", e.getField(), "error", e.getMessage())
-                        "error", e.getMessage()
+        );
-                ));
       }
     }
     User user = userService.register(
-                req.getUsername(), req.getEmail(), req.getPassword(), "", registerModeService.getRegisterMode());
+      req.getUsername(),
+      req.getEmail(),
+      req.getPassword(),
+      "",
+      registerModeService.getRegisterMode()
+    );
     // 发送确认邮件
     userService.sendVerifyMail(user, VerifyType.REGISTER);
     if (!user.isApproved()) {
@@ -84,6 +105,12 @@ public class AuthController {
   }
 
   @PostMapping("/verify")
+  @Operation(summary = "Verify account", description = "Verify registration code")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Verification result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> verify(@RequestBody VerifyRequest req) {
     Optional<User> userOpt = userService.findByUsername(req.getUsername());
     if (userOpt.isEmpty()) {
@@ -94,23 +121,39 @@ public class AuthController {
       User user = userOpt.get();
 
       if (user.isApproved()) {
-                return ResponseEntity.ok(Map.of(
+        return ResponseEntity.ok(
-                        "message", "Verified and isApproved",
+          Map.of(
-                        "reason_code", "VERIFIED_AND_APPROVED",
+            "message",
-                        "token", jwtService.generateToken(req.getUsername())
+            "Verified and isApproved",
-                ));
+            "reason_code",
+            "VERIFIED_AND_APPROVED",
+            "token",
+            jwtService.generateToken(req.getUsername())
+          )
+        );
       } else {
-                return ResponseEntity.ok(Map.of(
+        return ResponseEntity.ok(
-                        "message", "Verified",
+          Map.of(
-                        "reason_code", "VERIFIED",
+            "message",
-                        "token", jwtService.generateReasonToken(req.getUsername())
+            "Verified",
-                ));
+            "reason_code",
+            "VERIFIED",
+            "token",
+            jwtService.generateReasonToken(req.getUsername())
+          )
+        );
       }
     }
     return ResponseEntity.badRequest().body(Map.of("error", "Invalid verification code"));
   }
 
   @PostMapping("/login")
+  @Operation(summary = "Login", description = "Authenticate with username/email and password")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Authentication result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> login(@RequestBody LoginRequest req) {
     if (captchaEnabled && loginCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid captcha"));
@@ -120,97 +163,154 @@ public class AuthController {
       userOpt = userService.findByEmail(req.getUsername());
     }
     if (userOpt.isEmpty() || !userService.matchesPassword(userOpt.get(), req.getPassword())) {
-            return ResponseEntity.badRequest().body(Map.of(
+      return ResponseEntity.badRequest().body(
-                    "error", "Invalid credentials",
+        Map.of("error", "Invalid credentials", "reason_code", "INVALID_CREDENTIALS")
-                    "reason_code", "INVALID_CREDENTIALS"));
+      );
     }
     User user = userOpt.get();
     if (!user.isVerified()) {
-            user = userService.register(user.getUsername(), user.getEmail(), user.getPassword(), user.getRegisterReason(), registerModeService.getRegisterMode());
+      user = userService.register(
+        user.getUsername(),
+        user.getEmail(),
+        user.getPassword(),
+        user.getRegisterReason(),
+        registerModeService.getRegisterMode()
+      );
       userService.sendVerifyMail(user, VerifyType.REGISTER);
-            return ResponseEntity.badRequest().body(Map.of(
+      return ResponseEntity.badRequest().body(
-                    "error", "User not verified",
+        Map.of(
-                    "reason_code", "NOT_VERIFIED",
+          "error",
-                    "user_name", user.getUsername()));
+          "User not verified",
+          "reason_code",
+          "NOT_VERIFIED",
+          "user_name",
+          user.getUsername()
+        )
+      );
     }
-        if (RegisterMode.WHITELIST.equals(registerModeService.getRegisterMode()) && !user.isApproved()) {
+    if (
+      RegisterMode.WHITELIST.equals(registerModeService.getRegisterMode()) && !user.isApproved()
+    ) {
       if (user.getRegisterReason() != null && !user.getRegisterReason().isEmpty()) {
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "error", "Account awaiting approval",
+          Map.of("error", "Account awaiting approval", "reason_code", "IS_APPROVING")
-                        "reason_code", "IS_APPROVING"
+        );
-                ));
       }
-            return ResponseEntity.badRequest().body(Map.of(
+      return ResponseEntity.badRequest().body(
-                    "error", "Register reason not approved",
+        Map.of(
-                    "reason_code", "NOT_APPROVED",
+          "error",
-                    "token", jwtService.generateReasonToken(user.getUsername())));
+          "Register reason not approved",
+          "reason_code",
+          "NOT_APPROVED",
+          "token",
+          jwtService.generateReasonToken(user.getUsername())
+        )
+      );
     }
     return ResponseEntity.ok(Map.of("token", jwtService.generateToken(user.getUsername())));
   }
 
   @PostMapping("/google")
+  @Operation(summary = "Login with Google", description = "Authenticate using Google account")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Authentication result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> loginWithGoogle(@RequestBody GoogleLoginRequest req) {
     boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
-        InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
+    InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(
+      req.getInviteToken()
+    );
     if (viaInvite && !inviteValidateResult.isValidate()) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid invite token"));
     }
     Optional<AuthResult> resultOpt = googleAuthService.authenticate(
       req.getIdToken(),
       registerModeService.getRegisterMode(),
-                viaInvite);
+      viaInvite
+    );
     if (resultOpt.isPresent()) {
       AuthResult result = resultOpt.get();
       if (viaInvite && result.isNewUser()) {
-                inviteService.consume(req.getInviteToken(), inviteValidateResult.getInviteToken().getInviter().getUsername());
+        inviteService.consume(
-                return ResponseEntity.ok(Map.of(
+          req.getInviteToken(),
-                        "token", jwtService.generateToken(result.getUser().getUsername()),
+          inviteValidateResult.getInviteToken().getInviter().getUsername()
-                        "reason_code", "INVITE_APPROVED"
+        );
-                ));
+        return ResponseEntity.ok(
+          Map.of(
+            "token",
+            jwtService.generateToken(result.getUser().getUsername()),
+            "reason_code",
+            "INVITE_APPROVED"
+          )
+        );
       }
       if (RegisterMode.DIRECT.equals(registerModeService.getRegisterMode())) {
-                return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+        return ResponseEntity.ok(
+          Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+        );
       }
       if (!result.getUser().isApproved()) {
-                if (result.getUser().getRegisterReason() != null && !result.getUser().getRegisterReason().isEmpty()) {
+        if (
-                    return ResponseEntity.badRequest().body(Map.of(
+          result.getUser().getRegisterReason() != null &&
-                            "error", "Account awaiting approval",
+          !result.getUser().getRegisterReason().isEmpty()
-                            "reason_code", "IS_APPROVING",
+        ) {
-                            "token", jwtService.generateReasonToken(result.getUser().getUsername())
+          return ResponseEntity.badRequest().body(
-                    ));
+            Map.of(
+              "error",
+              "Account awaiting approval",
+              "reason_code",
+              "IS_APPROVING",
+              "token",
+              jwtService.generateReasonToken(result.getUser().getUsername())
+            )
+          );
         }
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "error", "Account awaiting approval",
+          Map.of(
-                        "reason_code", "NOT_APPROVED",
+            "error",
-                        "token", jwtService.generateReasonToken(result.getUser().getUsername())
+            "Account awaiting approval",
-                ));
+            "reason_code",
+            "NOT_APPROVED",
+            "token",
+            jwtService.generateReasonToken(result.getUser().getUsername())
+          )
+        );
       }
 
-            return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+      return ResponseEntity.ok(
+        Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+      );
     }
-        return ResponseEntity.badRequest().body(Map.of(
+    return ResponseEntity.badRequest().body(
-                "error", "Invalid google token",
+      Map.of("error", "Invalid google token", "reason_code", "INVALID_CREDENTIALS")
-                "reason_code", "INVALID_CREDENTIALS"
+    );
-        ));
   }
 
-
   @PostMapping("/reason")
+  @Operation(
+    summary = "Submit register reason",
+    description = "Submit registration reason for approval"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Submission result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> reason(@RequestBody MakeReasonRequest req) {
     String username = jwtService.validateAndGetSubjectForReason(req.getToken());
     Optional<User> userOpt = userService.findByUsername(username);
     if (userOpt.isEmpty()) {
-            return ResponseEntity.badRequest().body(Map.of(
+      return ResponseEntity.badRequest().body(
-                    "error", "Invalid token, Please re-login",
+        Map.of("error", "Invalid token, Please re-login", "reason_code", "INVALID_CREDENTIALS")
-                    "reason_code", "INVALID_CREDENTIALS"
+      );
-            ));
     }
 
     if (req.getReason() == null || req.getReason().trim().length() <= 20) {
-             return ResponseEntity.badRequest().body(Map.of(
+      return ResponseEntity.badRequest().body(
-                    "error", "Reason's length must longer than 20",
+        Map.of("error", "Reason's length must longer than 20", "reason_code", "INVALID_CREDENTIALS")
-                    "reason_code", "INVALID_CREDENTIALS"
+      );
-            ));
     }
 
     User user = userOpt.get();
@@ -224,9 +324,17 @@ public class AuthController {
   }
 
   @PostMapping("/github")
+  @Operation(summary = "Login with GitHub", description = "Authenticate using GitHub account")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Authentication result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> loginWithGithub(@RequestBody GithubLoginRequest req) {
     boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
-        InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
+    InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(
+      req.getInviteToken()
+    );
     if (viaInvite && !inviteValidateResult.isValidate()) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid invite token"));
     }
@@ -234,47 +342,79 @@ public class AuthController {
       req.getCode(),
       registerModeService.getRegisterMode(),
       req.getRedirectUri(),
-                viaInvite);
+      viaInvite
+    );
     if (resultOpt.isPresent()) {
       AuthResult result = resultOpt.get();
       if (viaInvite && result.isNewUser()) {
-                inviteService.consume(req.getInviteToken(), inviteValidateResult.getInviteToken().getInviter().getUsername());
+        inviteService.consume(
-                return ResponseEntity.ok(Map.of(
+          req.getInviteToken(),
-                        "token", jwtService.generateToken(result.getUser().getUsername()),
+          inviteValidateResult.getInviteToken().getInviter().getUsername()
-                        "reason_code", "INVITE_APPROVED"
+        );
-                ));
+        return ResponseEntity.ok(
+          Map.of(
+            "token",
+            jwtService.generateToken(result.getUser().getUsername()),
+            "reason_code",
+            "INVITE_APPROVED"
+          )
+        );
       }
       if (RegisterMode.DIRECT.equals(registerModeService.getRegisterMode())) {
-                return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+        return ResponseEntity.ok(
+          Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+        );
       }
       if (!result.getUser().isApproved()) {
-                if (result.getUser().getRegisterReason() != null && !result.getUser().getRegisterReason().isEmpty()) {
+        if (
+          result.getUser().getRegisterReason() != null &&
+          !result.getUser().getRegisterReason().isEmpty()
+        ) {
           // 已填写注册理由
-                    return ResponseEntity.badRequest().body(Map.of(
+          return ResponseEntity.badRequest().body(
-                            "error", "Account awaiting approval",
+            Map.of(
-                            "reason_code", "IS_APPROVING",
+              "error",
-                            "token", jwtService.generateReasonToken(result.getUser().getUsername())
+              "Account awaiting approval",
-                    ));
+              "reason_code",
+              "IS_APPROVING",
+              "token",
+              jwtService.generateReasonToken(result.getUser().getUsername())
+            )
+          );
         }
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "error", "Account awaiting approval",
+          Map.of(
-                        "reason_code", "NOT_APPROVED",
+            "error",
-                        "token", jwtService.generateReasonToken(result.getUser().getUsername())
+            "Account awaiting approval",
-                ));
+            "reason_code",
+            "NOT_APPROVED",
+            "token",
+            jwtService.generateReasonToken(result.getUser().getUsername())
+          )
+        );
       }
 
-            return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+      return ResponseEntity.ok(
+        Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+      );
     }
-        return ResponseEntity.badRequest().body(Map.of(
+    return ResponseEntity.badRequest().body(
-                "error", "Invalid github code",
+      Map.of("error", "Invalid github code", "reason_code", "INVALID_CREDENTIALS")
-                "reason_code", "INVALID_CREDENTIALS"
+    );
-        ));
   }
 
   @PostMapping("/discord")
+  @Operation(summary = "Login with Discord", description = "Authenticate using Discord account")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Authentication result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> loginWithDiscord(@RequestBody DiscordLoginRequest req) {
     boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
-        InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
+    InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(
+      req.getInviteToken()
+    );
     if (viaInvite && !inviteValidateResult.isValidate()) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid invite token"));
     }
@@ -282,46 +422,78 @@ public class AuthController {
       req.getCode(),
       registerModeService.getRegisterMode(),
       req.getRedirectUri(),
-                viaInvite);
+      viaInvite
+    );
     if (resultOpt.isPresent()) {
       AuthResult result = resultOpt.get();
       if (viaInvite && result.isNewUser()) {
-                inviteService.consume(req.getInviteToken(), inviteValidateResult.getInviteToken().getInviter().getUsername());
+        inviteService.consume(
-                return ResponseEntity.ok(Map.of(
+          req.getInviteToken(),
-                        "token", jwtService.generateToken(result.getUser().getUsername()),
+          inviteValidateResult.getInviteToken().getInviter().getUsername()
-                        "reason_code", "INVITE_APPROVED"
+        );
-                ));
+        return ResponseEntity.ok(
+          Map.of(
+            "token",
+            jwtService.generateToken(result.getUser().getUsername()),
+            "reason_code",
+            "INVITE_APPROVED"
+          )
+        );
       }
       if (RegisterMode.DIRECT.equals(registerModeService.getRegisterMode())) {
-                return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+        return ResponseEntity.ok(
+          Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+        );
       }
       if (!result.getUser().isApproved()) {
-                if (result.getUser().getRegisterReason() != null && !result.getUser().getRegisterReason().isEmpty()) {
+        if (
-                    return ResponseEntity.badRequest().body(Map.of(
+          result.getUser().getRegisterReason() != null &&
-                            "error", "Account awaiting approval",
+          !result.getUser().getRegisterReason().isEmpty()
-                            "reason_code", "IS_APPROVING",
+        ) {
-                            "token", jwtService.generateReasonToken(result.getUser().getUsername())
+          return ResponseEntity.badRequest().body(
-                    ));
+            Map.of(
+              "error",
+              "Account awaiting approval",
+              "reason_code",
+              "IS_APPROVING",
+              "token",
+              jwtService.generateReasonToken(result.getUser().getUsername())
+            )
+          );
         }
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "error", "Account awaiting approval",
+          Map.of(
-                        "reason_code", "NOT_APPROVED",
+            "error",
-                        "token", jwtService.generateReasonToken(result.getUser().getUsername())
+            "Account awaiting approval",
-                ));
+            "reason_code",
+            "NOT_APPROVED",
+            "token",
+            jwtService.generateReasonToken(result.getUser().getUsername())
+          )
+        );
       }
 
-            return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+      return ResponseEntity.ok(
+        Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+      );
     }
-        return ResponseEntity.badRequest().body(Map.of(
+    return ResponseEntity.badRequest().body(
-                "error", "Invalid discord code",
+      Map.of("error", "Invalid discord code", "reason_code", "INVALID_CREDENTIALS")
-                "reason_code", "INVALID_CREDENTIALS"
+    );
-        ));
   }
 
   @PostMapping("/twitter")
+  @Operation(summary = "Login with Twitter", description = "Authenticate using Twitter account")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Authentication result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> loginWithTwitter(@RequestBody TwitterLoginRequest req) {
     boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
-        InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
+    InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(
+      req.getInviteToken()
+    );
     if (viaInvite && !inviteValidateResult.isValidate()) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid invite token"));
     }
@@ -330,93 +502,162 @@ public class AuthController {
       req.getCodeVerifier(),
       registerModeService.getRegisterMode(),
       req.getRedirectUri(),
-                viaInvite);
+      viaInvite
+    );
     if (resultOpt.isPresent()) {
       AuthResult result = resultOpt.get();
       if (viaInvite && result.isNewUser()) {
-                inviteService.consume(req.getInviteToken(), inviteValidateResult.getInviteToken().getInviter().getUsername());
+        inviteService.consume(
-                return ResponseEntity.ok(Map.of(
+          req.getInviteToken(),
-                        "token", jwtService.generateToken(result.getUser().getUsername()),
+          inviteValidateResult.getInviteToken().getInviter().getUsername()
-                        "reason_code", "INVITE_APPROVED"
+        );
-                ));
+        return ResponseEntity.ok(
+          Map.of(
+            "token",
+            jwtService.generateToken(result.getUser().getUsername()),
+            "reason_code",
+            "INVITE_APPROVED"
+          )
+        );
       }
       if (RegisterMode.DIRECT.equals(registerModeService.getRegisterMode())) {
-                return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+        return ResponseEntity.ok(
+          Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+        );
       }
       if (!result.getUser().isApproved()) {
-                if (result.getUser().getRegisterReason() != null && !result.getUser().getRegisterReason().isEmpty()) {
+        if (
-                    return ResponseEntity.badRequest().body(Map.of(
+          result.getUser().getRegisterReason() != null &&
-                            "error", "Account awaiting approval",
+          !result.getUser().getRegisterReason().isEmpty()
-                            "reason_code", "IS_APPROVING",
+        ) {
-                            "token", jwtService.generateReasonToken(result.getUser().getUsername())
+          return ResponseEntity.badRequest().body(
-                    ));
+            Map.of(
+              "error",
+              "Account awaiting approval",
+              "reason_code",
+              "IS_APPROVING",
+              "token",
+              jwtService.generateReasonToken(result.getUser().getUsername())
+            )
+          );
         }
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "error", "Account awaiting approval",
+          Map.of(
-                        "reason_code", "NOT_APPROVED",
+            "error",
-                        "token", jwtService.generateReasonToken(result.getUser().getUsername())
+            "Account awaiting approval",
-                ));
+            "reason_code",
+            "NOT_APPROVED",
+            "token",
+            jwtService.generateReasonToken(result.getUser().getUsername())
+          )
+        );
       }
 
-            return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+      return ResponseEntity.ok(
+        Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+      );
     }
-        return ResponseEntity.badRequest().body(Map.of(
+    return ResponseEntity.badRequest().body(
-                "error", "Invalid twitter code",
+      Map.of("error", "Invalid twitter code", "reason_code", "INVALID_CREDENTIALS")
-                "reason_code", "INVALID_CREDENTIALS"
+    );
-        ));
   }
 
   @PostMapping("/telegram")
+  @Operation(summary = "Login with Telegram", description = "Authenticate using Telegram data")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Authentication result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> loginWithTelegram(@RequestBody TelegramLoginRequest req) {
     boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
-        InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
+    InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(
+      req.getInviteToken()
+    );
     if (viaInvite && !inviteValidateResult.isValidate()) {
       return ResponseEntity.badRequest().body(Map.of("error", "Invalid invite token"));
     }
     Optional<AuthResult> resultOpt = telegramAuthService.authenticate(
       req,
       registerModeService.getRegisterMode(),
-                viaInvite);
+      viaInvite
+    );
     if (resultOpt.isPresent()) {
       AuthResult result = resultOpt.get();
       if (viaInvite && result.isNewUser()) {
-                inviteService.consume(req.getInviteToken(), inviteValidateResult.getInviteToken().getInviter().getUsername());
+        inviteService.consume(
-                return ResponseEntity.ok(Map.of(
+          req.getInviteToken(),
-                        "token", jwtService.generateToken(result.getUser().getUsername()),
+          inviteValidateResult.getInviteToken().getInviter().getUsername()
-                        "reason_code", "INVITE_APPROVED"
+        );
-                ));
+        return ResponseEntity.ok(
+          Map.of(
+            "token",
+            jwtService.generateToken(result.getUser().getUsername()),
+            "reason_code",
+            "INVITE_APPROVED"
+          )
+        );
       }
       if (RegisterMode.DIRECT.equals(registerModeService.getRegisterMode())) {
-                return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+        return ResponseEntity.ok(
+          Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+        );
       }
       if (!result.getUser().isApproved()) {
-                if (result.getUser().getRegisterReason() != null && !result.getUser().getRegisterReason().isEmpty()) {
+        if (
-                    return ResponseEntity.badRequest().body(Map.of(
+          result.getUser().getRegisterReason() != null &&
-                            "error", "Account awaiting approval",
+          !result.getUser().getRegisterReason().isEmpty()
-                            "reason_code", "IS_APPROVING",
+        ) {
-                            "token", jwtService.generateReasonToken(result.getUser().getUsername())
+          return ResponseEntity.badRequest().body(
-                    ));
+            Map.of(
+              "error",
+              "Account awaiting approval",
+              "reason_code",
+              "IS_APPROVING",
+              "token",
+              jwtService.generateReasonToken(result.getUser().getUsername())
+            )
+          );
         }
-                return ResponseEntity.badRequest().body(Map.of(
+        return ResponseEntity.badRequest().body(
-                        "error", "Account awaiting approval",
+          Map.of(
-                        "reason_code", "NOT_APPROVED",
+            "error",
-                        "token", jwtService.generateReasonToken(result.getUser().getUsername())
+            "Account awaiting approval",
-                ));
+            "reason_code",
+            "NOT_APPROVED",
+            "token",
+            jwtService.generateReasonToken(result.getUser().getUsername())
+          )
+        );
       }
-            return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+      return ResponseEntity.ok(
+        Map.of("token", jwtService.generateToken(result.getUser().getUsername()))
+      );
     }
-        return ResponseEntity.badRequest().body(Map.of(
+    return ResponseEntity.badRequest().body(
-                "error", "Invalid telegram data",
+      Map.of("error", "Invalid telegram data", "reason_code", "INVALID_CREDENTIALS")
-                "reason_code", "INVALID_CREDENTIALS"
+    );
-        ));
   }
 
   @GetMapping("/check")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Check token", description = "Validate JWT token")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Token valid",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> checkToken() {
     return ResponseEntity.ok(Map.of("valid", true));
   }
 
   @PostMapping("/forgot/send")
+  @Operation(summary = "Send reset code", description = "Send verification code for password reset")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Sending result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> sendReset(@RequestBody ForgotPasswordRequest req) {
     Optional<User> userOpt = userService.findByEmail(req.getEmail());
     if (userOpt.isEmpty()) {
@@ -427,6 +668,12 @@ public class AuthController {
   }
 
   @PostMapping("/forgot/verify")
+  @Operation(summary = "Verify reset code", description = "Verify password reset code")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Verification result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> verifyReset(@RequestBody VerifyForgotRequest req) {
     Optional<User> userOpt = userService.findByEmail(req.getEmail());
     if (userOpt.isEmpty()) {
@@ -441,16 +688,21 @@ public class AuthController {
   }
 
   @PostMapping("/forgot/reset")
+  @Operation(summary = "Reset password", description = "Reset user password after verification")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reset result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public ResponseEntity<?> resetPassword(@RequestBody ResetPasswordRequest req) {
     String username = jwtService.validateAndGetSubjectForReset(req.getToken());
     try {
       userService.updatePassword(username, req.getPassword());
       return ResponseEntity.ok(Map.of("message", "Password updated"));
     } catch (FieldException e) {
-            return ResponseEntity.badRequest().body(Map.of(
+      return ResponseEntity.badRequest().body(
-                    "field", e.getField(),
+        Map.of("field", e.getField(), "error", e.getMessage())
-                    "error", e.getMessage()
+      );
-            ));
     }
   }
 

backend/src/main/java/com/openisle/controller/CategoryController.java

@@ -8,53 +8,96 @@ import com.openisle.mapper.PostMapper;
 import com.openisle.model.Category;
 import com.openisle.service.CategoryService;
 import com.openisle.service.PostService;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
-
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/api/categories")
 @RequiredArgsConstructor
 public class CategoryController {
+
   private final CategoryService categoryService;
   private final PostService postService;
   private final PostMapper postMapper;
   private final CategoryMapper categoryMapper;
 
   @PostMapping
+  @Operation(summary = "Create category", description = "Create a new category")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Created category",
+    content = @Content(schema = @Schema(implementation = CategoryDto.class))
+  )
   public CategoryDto create(@RequestBody CategoryRequest req) {
-        Category c = categoryService.createCategory(req.getName(), req.getDescription(), req.getIcon(), req.getSmallIcon());
+    Category c = categoryService.createCategory(
+      req.getName(),
+      req.getDescription(),
+      req.getIcon(),
+      req.getSmallIcon()
+    );
     long count = postService.countPostsByCategory(c.getId());
     return categoryMapper.toDto(c, count);
   }
 
   @PutMapping("/{id}")
+  @Operation(summary = "Update category", description = "Update an existing category")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Updated category",
+    content = @Content(schema = @Schema(implementation = CategoryDto.class))
+  )
   public CategoryDto update(@PathVariable Long id, @RequestBody CategoryRequest req) {
-        Category c = categoryService.updateCategory(id, req.getName(), req.getDescription(), req.getIcon(), req.getSmallIcon());
+    Category c = categoryService.updateCategory(
+      id,
+      req.getName(),
+      req.getDescription(),
+      req.getIcon(),
+      req.getSmallIcon()
+    );
     long count = postService.countPostsByCategory(c.getId());
     return categoryMapper.toDto(c, count);
   }
 
   @DeleteMapping("/{id}")
+  @Operation(summary = "Delete category", description = "Remove a category by id")
+  @ApiResponse(responseCode = "200", description = "Category deleted")
   public void delete(@PathVariable Long id) {
     categoryService.deleteCategory(id);
   }
 
   @GetMapping
+  @Operation(summary = "List categories", description = "Get all categories")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of categories",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = CategoryDto.class)))
+  )
   public List<CategoryDto> list() {
     List<Category> all = categoryService.listCategories();
     List<Long> ids = all.stream().map(Category::getId).toList();
     Map<Long, Long> postsCntByCategoryIds = postService.countPostsByCategoryIds(ids);
-        return all.stream()
+    return all
+      .stream()
       .map(c -> categoryMapper.toDto(c, postsCntByCategoryIds.getOrDefault(c.getId(), 0L)))
       .sorted((a, b) -> Long.compare(b.getCount(), a.getCount()))
       .collect(Collectors.toList());
   }
 
   @GetMapping("/{id}")
+  @Operation(summary = "Get category", description = "Get category by id")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Category detail",
+    content = @Content(schema = @Schema(implementation = CategoryDto.class))
+  )
   public CategoryDto get(@PathVariable Long id) {
     Category c = categoryService.getCategory(id);
     long count = postService.countPostsByCategory(c.getId());
@@ -62,10 +105,21 @@ public class CategoryController {
   }
 
   @GetMapping("/{id}/posts")
-    public List<PostSummaryDto> listPostsByCategory(@PathVariable Long id,
+  @Operation(summary = "List posts by category", description = "Get posts under a category")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  public List<PostSummaryDto> listPostsByCategory(
+    @PathVariable Long id,
     @RequestParam(value = "page", required = false) Integer page,
-                                                    @RequestParam(value = "pageSize", required = false) Integer pageSize) {
+    @RequestParam(value = "pageSize", required = false) Integer pageSize
-        return postService.listPostsByCategories(java.util.List.of(id), page, pageSize)
+  ) {
+    return postService
+      .listPostsByCategories(java.util.List.of(id), page, pageSize)
       .stream()
       .map(postMapper::toSummaryDto)
       .collect(Collectors.toList());

backend/src/main/java/com/openisle/controller/ChannelController.java

@@ -5,37 +5,65 @@ import com.openisle.model.User;
 import com.openisle.repository.UserRepository;
 import com.openisle.service.ChannelService;
 import com.openisle.service.MessageService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-
 @RestController
 @RequestMapping("/api/channels")
 @RequiredArgsConstructor
 public class ChannelController {
+
   private final ChannelService channelService;
   private final MessageService messageService;
   private final UserRepository userRepository;
 
   private Long getCurrentUserId(Authentication auth) {
-        User user = userRepository.findByUsername(auth.getName())
+    User user = userRepository
+      .findByUsername(auth.getName())
       .orElseThrow(() -> new IllegalArgumentException("User not found"));
     return user.getId();
   }
 
   @GetMapping
+  @Operation(summary = "List channels", description = "List channels for the current user")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Channels",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = ChannelDto.class)))
+  )
+  @SecurityRequirement(name = "JWT")
   public List<ChannelDto> listChannels(Authentication auth) {
     return channelService.listChannels(getCurrentUserId(auth));
   }
 
   @PostMapping("/{channelId}/join")
+  @Operation(summary = "Join channel", description = "Join a channel")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Joined channel",
+    content = @Content(schema = @Schema(implementation = ChannelDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public ChannelDto joinChannel(@PathVariable Long channelId, Authentication auth) {
     return channelService.joinChannel(channelId, getCurrentUserId(auth));
   }
 
   @GetMapping("/unread-count")
+  @Operation(summary = "Unread count", description = "Get unread channel count")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unread count",
+    content = @Content(schema = @Schema(implementation = Long.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public long unreadCount(Authentication auth) {
     return messageService.getUnreadChannelCount(getCurrentUserId(auth));
   }

backend/src/main/java/com/openisle/controller/CommentController.java

@@ -1,13 +1,24 @@
 package com.openisle.controller;
 
-import com.openisle.model.Comment;
 import com.openisle.dto.CommentDto;
 import com.openisle.dto.CommentRequest;
+import com.openisle.dto.PostChangeLogDto;
+import com.openisle.dto.TimelineItemDto;
 import com.openisle.mapper.CommentMapper;
-import com.openisle.service.CaptchaService;
+import com.openisle.mapper.PostChangeLogMapper;
-import com.openisle.service.CommentService;
+import com.openisle.model.Comment;
-import com.openisle.service.LevelService;
+import com.openisle.model.CommentSort;
-import com.openisle.service.PointService;
+import com.openisle.service.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
@@ -15,19 +26,19 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
 @RestController
 @RequestMapping("/api")
 @RequiredArgsConstructor
 @Slf4j
 public class CommentController {
+
   private final CommentService commentService;
   private final LevelService levelService;
   private final CaptchaService captchaService;
   private final CommentMapper commentMapper;
   private final PointService pointService;
+  private final PostChangeLogService changeLogService;
+  private final PostChangeLogMapper postChangeLogMapper;
 
   @Value("${app.captcha.enabled:false}")
   private boolean captchaEnabled;
@@ -36,9 +47,18 @@ public class CommentController {
   private boolean commentCaptchaEnabled;
 
   @PostMapping("/posts/{postId}/comments")
-    public ResponseEntity<CommentDto> createComment(@PathVariable Long postId,
+  @Operation(summary = "Create comment", description = "Add a comment to a post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Created comment",
+    content = @Content(schema = @Schema(implementation = CommentDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<CommentDto> createComment(
+    @PathVariable Long postId,
     @RequestBody CommentRequest req,
-                                                    Authentication auth) {
+    Authentication auth
+  ) {
     log.debug("createComment called by user {} for post {}", auth.getName(), postId);
     if (captchaEnabled && commentCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
       log.debug("Captcha verification failed for user {} on post {}", auth.getName(), postId);
@@ -53,9 +73,18 @@ public class CommentController {
   }
 
   @PostMapping("/comments/{commentId}/replies")
-    public ResponseEntity<CommentDto> replyComment(@PathVariable Long commentId,
+  @Operation(summary = "Reply to comment", description = "Reply to an existing comment")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reply created",
+    content = @Content(schema = @Schema(implementation = CommentDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<CommentDto> replyComment(
+    @PathVariable Long commentId,
     @RequestBody CommentRequest req,
-                                                   Authentication auth) {
+    Authentication auth
+  ) {
     log.debug("replyComment called by user {} for comment {}", auth.getName(), commentId);
     if (captchaEnabled && commentCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
       log.debug("Captcha verification failed for user {} on comment {}", auth.getName(), commentId);
@@ -69,17 +98,72 @@ public class CommentController {
   }
 
   @GetMapping("/posts/{postId}/comments")
-    public List<CommentDto> listComments(@PathVariable Long postId,
+  @Operation(summary = "List comments", description = "List comments for a post")
-                                         @RequestParam(value = "sort", required = false, defaultValue = "OLDEST") com.openisle.model.CommentSort sort) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Comments",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = TimelineItemDto.class))
+    )
+  )
+  public List<TimelineItemDto<?>> listComments(
+    @PathVariable Long postId,
+    @RequestParam(value = "sort", required = false, defaultValue = "OLDEST") CommentSort sort
+  ) {
     log.debug("listComments called for post {} with sort {}", postId, sort);
-        List<CommentDto> list = commentService.getCommentsForPost(postId, sort).stream()
+    List<CommentDto> commentDtoList = commentService
+      .getCommentsForPost(postId, sort)
+      .stream()
       .map(commentMapper::toDtoWithReplies)
       .collect(Collectors.toList());
-        log.debug("listComments returning {} comments", list.size());
+    List<PostChangeLogDto> postChangeLogDtoList = changeLogService
-        return list;
+      .listLogs(postId)
+      .stream()
+      .map(postChangeLogMapper::toDto)
+      .collect(Collectors.toList());
+    List<TimelineItemDto<?>> itemDtoList = new ArrayList<>();
+
+    itemDtoList.addAll(
+      commentDtoList
+        .stream()
+        .map(c ->
+          new TimelineItemDto<>(
+            c.getId(),
+            "comment",
+            c.getCreatedAt(),
+            c // payload 是 CommentDto
+          )
+        )
+        .toList()
+    );
+
+    itemDtoList.addAll(
+      postChangeLogDtoList
+        .stream()
+        .map(l ->
+          new TimelineItemDto<>(
+            l.getId(),
+            "log",
+            l.getTime(), // 注意字段名不一样
+            l // payload 是 PostChangeLogDto
+          )
+        )
+        .toList()
+    );
+    // 排序
+    Comparator<TimelineItemDto<?>> comparator = Comparator.comparing(TimelineItemDto::getCreatedAt);
+    if (CommentSort.NEWEST.equals(sort)) {
+      comparator = comparator.reversed();
+    }
+    itemDtoList.sort(comparator);
+    log.debug("listComments returning {} comments", itemDtoList.size());
+    return itemDtoList;
   }
 
   @DeleteMapping("/comments/{id}")
+  @Operation(summary = "Delete comment", description = "Delete a comment")
+  @ApiResponse(responseCode = "200", description = "Deleted")
+  @SecurityRequirement(name = "JWT")
   public void deleteComment(@PathVariable Long id, Authentication auth) {
     log.debug("deleteComment called by user {} for comment {}", auth.getName(), id);
     commentService.deleteComment(auth.getName(), id);
@@ -87,12 +171,26 @@ public class CommentController {
   }
 
   @PostMapping("/comments/{id}/pin")
+  @Operation(summary = "Pin comment", description = "Pin a comment")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Pinned comment",
+    content = @Content(schema = @Schema(implementation = CommentDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public CommentDto pinComment(@PathVariable Long id, Authentication auth) {
     log.debug("pinComment called by user {} for comment {}", auth.getName(), id);
     return commentMapper.toDto(commentService.pinComment(auth.getName(), id));
   }
 
   @PostMapping("/comments/{id}/unpin")
+  @Operation(summary = "Unpin comment", description = "Unpin a comment")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unpinned comment",
+    content = @Content(schema = @Schema(implementation = CommentDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public CommentDto unpinComment(@PathVariable Long id, Authentication auth) {
     log.debug("unpinComment called by user {} for comment {}", auth.getName(), id);
     return commentMapper.toDto(commentService.unpinComment(auth.getName(), id));

backend/src/main/java/com/openisle/controller/ConfigController.java

@@ -2,6 +2,10 @@ package com.openisle.controller;
 
 import com.openisle.dto.SiteConfigDto;
 import com.openisle.service.RegisterModeService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -33,6 +37,12 @@ public class ConfigController {
   private final RegisterModeService registerModeService;
 
   @GetMapping("/config")
+  @Operation(summary = "Site config", description = "Get site configuration")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Site configuration",
+    content = @Content(schema = @Schema(implementation = SiteConfigDto.class))
+  )
   public SiteConfigDto getConfig() {
     SiteConfigDto resp = new SiteConfigDto();
     resp.setCaptchaEnabled(captchaEnabled);

backend/src/main/java/com/openisle/controller/DraftController.java

@@ -5,6 +5,11 @@ import com.openisle.dto.DraftRequest;
 import com.openisle.mapper.DraftMapper;
 import com.openisle.model.Draft;
 import com.openisle.service.DraftService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
@@ -14,23 +19,48 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api/drafts")
 @RequiredArgsConstructor
 public class DraftController {
+
   private final DraftService draftService;
   private final DraftMapper draftMapper;
 
   @PostMapping
+  @Operation(summary = "Save draft", description = "Save a draft for current user")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Draft saved",
+    content = @Content(schema = @Schema(implementation = DraftDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public ResponseEntity<DraftDto> saveDraft(@RequestBody DraftRequest req, Authentication auth) {
-        Draft draft = draftService.saveDraft(auth.getName(), req.getCategoryId(), req.getTitle(), req.getContent(), req.getTagIds());
+    Draft draft = draftService.saveDraft(
+      auth.getName(),
+      req.getCategoryId(),
+      req.getTitle(),
+      req.getContent(),
+      req.getTagIds()
+    );
     return ResponseEntity.ok(draftMapper.toDto(draft));
   }
 
   @GetMapping("/me")
+  @Operation(summary = "Get my draft", description = "Get current user's draft")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Draft details",
+    content = @Content(schema = @Schema(implementation = DraftDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public ResponseEntity<DraftDto> getMyDraft(Authentication auth) {
-        return draftService.getDraft(auth.getName())
+    return draftService
+      .getDraft(auth.getName())
       .map(d -> ResponseEntity.ok(draftMapper.toDto(d)))
       .orElseGet(() -> ResponseEntity.noContent().build());
   }
 
   @DeleteMapping("/me")
+  @Operation(summary = "Delete my draft", description = "Delete current user's draft")
+  @ApiResponse(responseCode = "200", description = "Draft deleted")
+  @SecurityRequirement(name = "JWT")
   public ResponseEntity<?> deleteMyDraft(Authentication auth) {
     draftService.deleteDraft(auth.getName());
     return ResponseEntity.ok().build();

backend/src/main/java/com/openisle/controller/GlobalExceptionHandler.java

@@ -1,21 +1,21 @@
 package com.openisle.controller;
 
-import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.ExceptionHandler;
-import org.springframework.web.bind.annotation.RestControllerAdvice;
 import com.openisle.exception.FieldException;
 import com.openisle.exception.NotFoundException;
 import com.openisle.exception.RateLimitException;
-
 import java.util.Map;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
 
 @RestControllerAdvice
 public class GlobalExceptionHandler {
 
   @ExceptionHandler(FieldException.class)
   public ResponseEntity<?> handleFieldException(FieldException ex) {
-        return ResponseEntity.badRequest()
+    return ResponseEntity.badRequest().body(
-                .body(Map.of("error", ex.getMessage(), "field", ex.getField()));
+      Map.of("error", ex.getMessage(), "field", ex.getField())
+    );
   }
 
   @ExceptionHandler(NotFoundException.class)
@@ -37,4 +37,3 @@ public class GlobalExceptionHandler {
     return ResponseEntity.badRequest().body(Map.of("error", message));
   }
 }
-

backend/src/main/java/com/openisle/controller/HelloController.java

@@ -1,12 +1,25 @@
 package com.openisle.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.Map;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
-import java.util.Map;
 
 @RestController
 public class HelloController {
+
   @GetMapping("/api/hello")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Hello endpoint", description = "Returns a greeting for authenticated users")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Greeting payload",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public Map<String, String> hello() {
     return Map.of("message", "Hello, Authenticated User");
   }

backend/src/main/java/com/openisle/controller/InviteController.java

@@ -1,21 +1,33 @@
 package com.openisle.controller;
 
 import com.openisle.service.InviteService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.Map;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
-import java.util.Map;
-
 @RestController
 @RequestMapping("/api/invite")
 @RequiredArgsConstructor
 public class InviteController {
+
   private final InviteService inviteService;
 
   @PostMapping("/generate")
+  @Operation(summary = "Generate invite", description = "Generate an invite token")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Invite token",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public Map<String, String> generate(Authentication auth) {
     String token = inviteService.generate(auth.getName());
     return Map.of("token", token);

backend/src/main/java/com/openisle/controller/MedalController.java

@@ -3,26 +3,44 @@ package com.openisle.controller;
 import com.openisle.dto.MedalDto;
 import com.openisle.dto.MedalSelectRequest;
 import com.openisle.service.MedalService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-
 @RestController
 @RequestMapping("/api/medals")
 @RequiredArgsConstructor
 public class MedalController {
+
   private final MedalService medalService;
 
   @GetMapping
+  @Operation(summary = "List medals", description = "List medals for user or globally")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of medals",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = MedalDto.class)))
+  )
   public List<MedalDto> getMedals(@RequestParam(value = "userId", required = false) Long userId) {
     return medalService.getMedals(userId);
   }
 
   @PostMapping("/select")
-    public ResponseEntity<Void> selectMedal(@RequestBody MedalSelectRequest req, Authentication auth) {
+  @Operation(summary = "Select medal", description = "Select a medal for current user")
+  @ApiResponse(responseCode = "200", description = "Medal selected")
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<Void> selectMedal(
+    @RequestBody MedalSelectRequest req,
+    Authentication auth
+  ) {
     try {
       medalService.selectMedal(auth.getName(), req.getType());
       return ResponseEntity.ok().build();

backend/src/main/java/com/openisle/controller/MessageController.java

@@ -10,6 +10,13 @@ import com.openisle.model.MessageConversation;
 import com.openisle.model.User;
 import com.openisle.repository.UserRepository;
 import com.openisle.service.MessageService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageRequest;
@@ -19,8 +26,6 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-
 @RestController
 @RequestMapping("/api/messages")
 @RequiredArgsConstructor
@@ -31,60 +36,146 @@ public class MessageController {
 
   // This is a placeholder for getting the current user's ID
   private Long getCurrentUserId(Authentication auth) {
-        User user = userRepository.findByUsername(auth.getName()).orElseThrow(() -> new IllegalArgumentException("Sender not found"));
+    User user = userRepository
+      .findByUsername(auth.getName())
+      .orElseThrow(() -> new IllegalArgumentException("Sender not found"));
     // In a real application, you would get this from the Authentication object
     return user.getId();
   }
 
   @GetMapping("/conversations")
+  @Operation(summary = "List conversations", description = "Get all conversations of current user")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of conversations",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = ConversationDto.class))
+    )
+  )
+  @SecurityRequirement(name = "JWT")
   public ResponseEntity<List<ConversationDto>> getConversations(Authentication auth) {
     List<ConversationDto> conversations = messageService.getConversations(getCurrentUserId(auth));
     return ResponseEntity.ok(conversations);
   }
 
   @GetMapping("/conversations/{conversationId}")
-    public ResponseEntity<ConversationDetailDto> getMessages(@PathVariable Long conversationId,
+  @Operation(summary = "Get conversation", description = "Get messages of a conversation")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Conversation detail",
+    content = @Content(schema = @Schema(implementation = ConversationDetailDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<ConversationDetailDto> getMessages(
+    @PathVariable Long conversationId,
     @RequestParam(defaultValue = "0") int page,
     @RequestParam(defaultValue = "20") int size,
-                                                               Authentication auth) {
+    Authentication auth
+  ) {
     Pageable pageable = PageRequest.of(page, size, Sort.by("createdAt").descending());
-        ConversationDetailDto conversationDetails = messageService.getConversationDetails(conversationId, getCurrentUserId(auth), pageable);
+    ConversationDetailDto conversationDetails = messageService.getConversationDetails(
+      conversationId,
+      getCurrentUserId(auth),
+      pageable
+    );
     return ResponseEntity.ok(conversationDetails);
   }
 
   @PostMapping
-    public ResponseEntity<MessageDto> sendMessage(@RequestBody MessageRequest req, Authentication auth) {
+  @Operation(summary = "Send message", description = "Send a direct message to a user")
-        Message message = messageService.sendMessage(getCurrentUserId(auth), req.getRecipientId(), req.getContent(), req.getReplyToId());
+  @ApiResponse(
+    responseCode = "200",
+    description = "Message sent",
+    content = @Content(schema = @Schema(implementation = MessageDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<MessageDto> sendMessage(
+    @RequestBody MessageRequest req,
+    Authentication auth
+  ) {
+    Message message = messageService.sendMessage(
+      getCurrentUserId(auth),
+      req.getRecipientId(),
+      req.getContent(),
+      req.getReplyToId()
+    );
     return ResponseEntity.ok(messageService.toDto(message));
   }
 
   @PostMapping("/conversations/{conversationId}/messages")
-    public ResponseEntity<MessageDto> sendMessageToConversation(@PathVariable Long conversationId,
+  @Operation(summary = "Send message to conversation", description = "Reply within a conversation")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Message sent",
+    content = @Content(schema = @Schema(implementation = MessageDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<MessageDto> sendMessageToConversation(
+    @PathVariable Long conversationId,
     @RequestBody ChannelMessageRequest req,
-                                                                Authentication auth) {
+    Authentication auth
-        Message message = messageService.sendMessageToConversation(getCurrentUserId(auth), conversationId, req.getContent(), req.getReplyToId());
+  ) {
+    Message message = messageService.sendMessageToConversation(
+      getCurrentUserId(auth),
+      conversationId,
+      req.getContent(),
+      req.getReplyToId()
+    );
     return ResponseEntity.ok(messageService.toDto(message));
   }
 
   @PostMapping("/conversations/{conversationId}/read")
+  @Operation(
+    summary = "Mark conversation read",
+    description = "Mark messages in conversation as read"
+  )
+  @ApiResponse(responseCode = "200", description = "Marked as read")
+  @SecurityRequirement(name = "JWT")
   public ResponseEntity<Void> markAsRead(@PathVariable Long conversationId, Authentication auth) {
     messageService.markConversationAsRead(conversationId, getCurrentUserId(auth));
     return ResponseEntity.ok().build();
   }
 
   @PostMapping("/conversations")
-    public ResponseEntity<CreateConversationResponse> findOrCreateConversation(@RequestBody CreateConversationRequest req, Authentication auth) {
+  @Operation(
-        MessageConversation conversation = messageService.findOrCreateConversation(getCurrentUserId(auth), req.getRecipientId());
+    summary = "Find or create conversation",
+    description = "Find existing or create new conversation with recipient"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Conversation id",
+    content = @Content(schema = @Schema(implementation = CreateConversationResponse.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<CreateConversationResponse> findOrCreateConversation(
+    @RequestBody CreateConversationRequest req,
+    Authentication auth
+  ) {
+    MessageConversation conversation = messageService.findOrCreateConversation(
+      getCurrentUserId(auth),
+      req.getRecipientId()
+    );
     return ResponseEntity.ok(new CreateConversationResponse(conversation.getId()));
   }
 
   @GetMapping("/unread-count")
+  @Operation(
+    summary = "Unread message count",
+    description = "Get unread message count for current user"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unread count",
+    content = @Content(schema = @Schema(implementation = Long.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public ResponseEntity<Long> getUnreadCount(Authentication auth) {
     return ResponseEntity.ok(messageService.getUnreadMessageCount(getCurrentUserId(auth)));
   }
 
   // A simple request DTO
   static class MessageRequest {
+
     private Long recipientId;
     private String content;
     private Long replyToId;
@@ -115,6 +206,7 @@ public class MessageController {
   }
 
   static class ChannelMessageRequest {
+
     private String content;
     private Long replyToId;
 

backend/src/main/java/com/openisle/controller/NotificationController.java

@@ -2,45 +2,90 @@ package com.openisle.controller;
 
 import com.openisle.dto.NotificationDto;
 import com.openisle.dto.NotificationMarkReadRequest;
-import com.openisle.dto.NotificationUnreadCountDto;
 import com.openisle.dto.NotificationPreferenceDto;
 import com.openisle.dto.NotificationPreferenceUpdateRequest;
+import com.openisle.dto.NotificationUnreadCountDto;
 import com.openisle.mapper.NotificationMapper;
 import com.openisle.service.NotificationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
 /** Endpoints for user notifications. */
 @RestController
 @RequestMapping("/api/notifications")
 @RequiredArgsConstructor
 public class NotificationController {
+
   private final NotificationService notificationService;
   private final NotificationMapper notificationMapper;
 
   @GetMapping
-    public List<NotificationDto> list(@RequestParam(value = "page", defaultValue = "0") int page,
+  @Operation(
+    summary = "List notifications",
+    description = "Retrieve notifications for the current user"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Notifications",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = NotificationDto.class))
+    )
+  )
+  @SecurityRequirement(name = "JWT")
+  public List<NotificationDto> list(
+    @RequestParam(value = "page", defaultValue = "0") int page,
     @RequestParam(value = "size", defaultValue = "30") int size,
-                                      Authentication auth) {
+    Authentication auth
-        return notificationService.listNotifications(auth.getName(), null, page, size).stream()
+  ) {
+    return notificationService
+      .listNotifications(auth.getName(), null, page, size)
+      .stream()
       .map(notificationMapper::toDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/unread")
-    public List<NotificationDto> listUnread(@RequestParam(value = "page", defaultValue = "0") int page,
+  @Operation(
+    summary = "List unread notifications",
+    description = "Retrieve unread notifications for the current user"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unread notifications",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = NotificationDto.class))
+    )
+  )
+  @SecurityRequirement(name = "JWT")
+  public List<NotificationDto> listUnread(
+    @RequestParam(value = "page", defaultValue = "0") int page,
     @RequestParam(value = "size", defaultValue = "30") int size,
-                                            Authentication auth) {
+    Authentication auth
-        return notificationService.listNotifications(auth.getName(), false, page, size).stream()
+  ) {
+    return notificationService
+      .listNotifications(auth.getName(), false, page, size)
+      .stream()
       .map(notificationMapper::toDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/unread-count")
+  @Operation(summary = "Unread count", description = "Get count of unread notifications")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Unread count",
+    content = @Content(schema = @Schema(implementation = NotificationUnreadCountDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public NotificationUnreadCountDto unreadCount(Authentication auth) {
     long count = notificationService.countUnread(auth.getName());
     NotificationUnreadCountDto uc = new NotificationUnreadCountDto();
@@ -49,27 +94,66 @@ public class NotificationController {
   }
 
   @PostMapping("/read")
+  @Operation(summary = "Mark notifications read", description = "Mark notifications as read")
+  @ApiResponse(responseCode = "200", description = "Marked read")
+  @SecurityRequirement(name = "JWT")
   public void markRead(@RequestBody NotificationMarkReadRequest req, Authentication auth) {
     notificationService.markRead(auth.getName(), req.getIds());
   }
 
   @GetMapping("/prefs")
+  @Operation(summary = "List preferences", description = "List notification preferences")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Preferences",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = NotificationPreferenceDto.class))
+    )
+  )
+  @SecurityRequirement(name = "JWT")
   public List<NotificationPreferenceDto> prefs(Authentication auth) {
     return notificationService.listPreferences(auth.getName());
   }
 
   @PostMapping("/prefs")
-    public void updatePref(@RequestBody NotificationPreferenceUpdateRequest req, Authentication auth) {
+  @Operation(summary = "Update preference", description = "Update notification preference")
+  @ApiResponse(responseCode = "200", description = "Preference updated")
+  @SecurityRequirement(name = "JWT")
+  public void updatePref(
+    @RequestBody NotificationPreferenceUpdateRequest req,
+    Authentication auth
+  ) {
     notificationService.updatePreference(auth.getName(), req.getType(), req.isEnabled());
   }
 
   @GetMapping("/email-prefs")
+  @Operation(
+    summary = "List email preferences",
+    description = "List email notification preferences"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Email preferences",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = NotificationPreferenceDto.class))
+    )
+  )
+  @SecurityRequirement(name = "JWT")
   public List<NotificationPreferenceDto> emailPrefs(Authentication auth) {
     return notificationService.listEmailPreferences(auth.getName());
   }
 
   @PostMapping("/email-prefs")
-    public void updateEmailPref(@RequestBody NotificationPreferenceUpdateRequest req, Authentication auth) {
+  @Operation(
+    summary = "Update email preference",
+    description = "Update email notification preference"
+  )
+  @ApiResponse(responseCode = "200", description = "Email preference updated")
+  @SecurityRequirement(name = "JWT")
+  public void updateEmailPref(
+    @RequestBody NotificationPreferenceUpdateRequest req,
+    Authentication auth
+  ) {
     notificationService.updateEmailPreference(auth.getName(), req.getType(), req.isEnabled());
   }
 }

backend/src/main/java/com/openisle/controller/OnlineController.java

@@ -1,13 +1,16 @@
 package com.openisle.controller;
 
 import com.openisle.config.CachingConfig;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import java.time.Duration;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.web.bind.annotation.*;
 
-import java.time.Duration;
-
 /**
  * @author smallclover
  * @since 2025-09-05
@@ -22,11 +25,19 @@ public class OnlineController {
   private static final String ONLINE_KEY = CachingConfig.ONLINE_CACHE_NAME + ":";
 
   @PostMapping("/heartbeat")
+  @Operation(summary = "Heartbeat", description = "Record user heartbeat")
+  @ApiResponse(responseCode = "200", description = "Heartbeat recorded")
   public void ping(@RequestParam String userId) {
     redisTemplate.opsForValue().set(ONLINE_KEY + userId, "1", Duration.ofSeconds(150));
   }
 
   @GetMapping("/count")
+  @Operation(summary = "Online count", description = "Get current online user count")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Online count",
+    content = @Content(schema = @Schema(implementation = Long.class))
+  )
   public long count() {
     return redisTemplate.keys(ONLINE_KEY + "*").size();
   }

backend/src/main/java/com/openisle/controller/PointHistoryController.java

@@ -3,6 +3,15 @@ package com.openisle.controller;
 import com.openisle.dto.PointHistoryDto;
 import com.openisle.mapper.PointHistoryMapper;
 import com.openisle.service.PointService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -10,27 +19,44 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-import java.util.List;
-import java.util.Map;
-import java.util.stream.Collectors;
-
 @RestController
 @RequestMapping("/api/point-histories")
 @RequiredArgsConstructor
 public class PointHistoryController {
+
   private final PointService pointService;
   private final PointHistoryMapper pointHistoryMapper;
 
   @GetMapping
+  @Operation(summary = "Point history", description = "List point history for current user")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of point histories",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PointHistoryDto.class))
+    )
+  )
+  @SecurityRequirement(name = "JWT")
   public List<PointHistoryDto> list(Authentication auth) {
-        return pointService.listHistory(auth.getName()).stream()
+    return pointService
+      .listHistory(auth.getName())
+      .stream()
       .map(pointHistoryMapper::toDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/trend")
-    public List<Map<String, Object>> trend(Authentication auth,
+  @Operation(summary = "Point trend", description = "Get point trend data for current user")
-                                          @RequestParam(value = "days", defaultValue = "30") int days) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Trend data",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class)))
+  )
+  @SecurityRequirement(name = "JWT")
+  public List<Map<String, Object>> trend(
+    Authentication auth,
+    @RequestParam(value = "days", defaultValue = "30") int days
+  ) {
     return pointService.trend(auth.getName(), days);
   }
 }

backend/src/main/java/com/openisle/controller/PointMallController.java

@@ -6,31 +6,52 @@ import com.openisle.mapper.PointGoodMapper;
 import com.openisle.model.User;
 import com.openisle.service.PointMallService;
 import com.openisle.service.UserService;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.security.core.Authentication;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.media.Content;
-
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.*;
 
 /** REST controller for point mall. */
 @RestController
 @RequestMapping("/api/point-goods")
 @RequiredArgsConstructor
 public class PointMallController {
+
   private final PointMallService pointMallService;
   private final UserService userService;
   private final PointGoodMapper pointGoodMapper;
 
   @GetMapping
+  @Operation(summary = "List goods", description = "List all point goods")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of goods",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = PointGoodDto.class)))
+  )
   public List<PointGoodDto> list() {
-        return pointMallService.listGoods().stream()
+    return pointMallService
+      .listGoods()
+      .stream()
       .map(pointGoodMapper::toDto)
       .collect(Collectors.toList());
   }
 
   @PostMapping("/redeem")
+  @Operation(summary = "Redeem good", description = "Redeem a point good")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Remaining points",
+    content = @Content(schema = @Schema(implementation = java.util.Map.class))
+  )
+  @SecurityRequirement(name = "JWT")
   public Map<String, Integer> redeem(@RequestBody PointRedeemRequest req, Authentication auth) {
     User user = userService.findByIdentifier(auth.getName()).orElseThrow();
     int point = pointMallService.redeem(user, req.getGoodId(), req.getContact());

backend/src/main/java/com/openisle/controller/PostChangeLogController.java

@@ -3,23 +3,34 @@ package com.openisle.controller;
 import com.openisle.dto.PostChangeLogDto;
 import com.openisle.mapper.PostChangeLogMapper;
 import com.openisle.service.PostChangeLogService;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
-
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import java.util.List;
 import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/api/posts")
 @RequiredArgsConstructor
 public class PostChangeLogController {
+
   private final PostChangeLogService changeLogService;
   private final PostChangeLogMapper mapper;
 
   @GetMapping("/{id}/change-logs")
+  @Operation(summary = "Post change logs", description = "List change logs for a post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Change logs",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostChangeLogDto.class))
+    )
+  )
   public List<PostChangeLogDto> listLogs(@PathVariable Long id) {
-        return changeLogService.listLogs(id).stream()
+    return changeLogService.listLogs(id).stream().map(mapper::toDto).collect(Collectors.toList());
-                .map(mapper::toDto)
-                .collect(Collectors.toList());
   }
 }

backend/src/main/java/com/openisle/controller/PostController.java

@@ -1,26 +1,36 @@
 package com.openisle.controller;
 
+import com.openisle.config.CachingConfig;
+import com.openisle.dto.PollDto;
 import com.openisle.dto.PostDetailDto;
 import com.openisle.dto.PostRequest;
 import com.openisle.dto.PostSummaryDto;
-import com.openisle.dto.PollDto;
 import com.openisle.mapper.PostMapper;
 import com.openisle.model.Post;
 import com.openisle.service.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.util.List;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.cache.annotation.Cacheable;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
 @RestController
 @RequestMapping("/api/posts")
 @RequiredArgsConstructor
 public class PostController {
+
   private final PostService postService;
+  private final CategoryService categoryService;
+  private final TagService tagService;
   private final LevelService levelService;
   private final CaptchaService captchaService;
   private final DraftService draftService;
@@ -35,16 +45,36 @@ public class PostController {
   private boolean postCaptchaEnabled;
 
   @PostMapping
-    public ResponseEntity<PostDetailDto> createPost(@RequestBody PostRequest req, Authentication auth) {
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Create post", description = "Create a new post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Created post",
+    content = @Content(schema = @Schema(implementation = PostDetailDto.class))
+  )
+  public ResponseEntity<PostDetailDto> createPost(
+    @RequestBody PostRequest req,
+    Authentication auth
+  ) {
     if (captchaEnabled && postCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
       return ResponseEntity.badRequest().build();
     }
-        Post post = postService.createPost(auth.getName(), req.getCategoryId(),
+    Post post = postService.createPost(
-                req.getTitle(), req.getContent(), req.getTagIds(),
+      auth.getName(),
-                req.getType(), req.getPrizeDescription(), req.getPrizeIcon(),
+      req.getCategoryId(),
-                req.getPrizeCount(), req.getPointCost(),
+      req.getTitle(),
-                req.getStartTime(), req.getEndTime(),
+      req.getContent(),
-                req.getOptions(), req.getMultiple());
+      req.getTagIds(),
+      req.getType(),
+      req.getPrizeDescription(),
+      req.getPrizeIcon(),
+      req.getPrizeCount(),
+      req.getPointCost(),
+      req.getStartTime(),
+      req.getEndTime(),
+      req.getOptions(),
+      req.getMultiple()
+    );
     draftService.deleteDraft(auth.getName());
     PostDetailDto dto = postMapper.toDetailDto(post, auth.getName());
     dto.setReward(levelService.awardForPost(auth.getName()));
@@ -53,29 +83,68 @@ public class PostController {
   }
 
   @PutMapping("/{id}")
-    public ResponseEntity<PostDetailDto> updatePost(@PathVariable Long id, @RequestBody PostRequest req,
+  @SecurityRequirement(name = "JWT")
-                                              Authentication auth) {
+  @Operation(summary = "Update post", description = "Update an existing post")
-        Post post = postService.updatePost(id, auth.getName(), req.getCategoryId(),
+  @ApiResponse(
-                req.getTitle(), req.getContent(), req.getTagIds());
+    responseCode = "200",
+    description = "Updated post",
+    content = @Content(schema = @Schema(implementation = PostDetailDto.class))
+  )
+  public ResponseEntity<PostDetailDto> updatePost(
+    @PathVariable Long id,
+    @RequestBody PostRequest req,
+    Authentication auth
+  ) {
+    Post post = postService.updatePost(
+      id,
+      auth.getName(),
+      req.getCategoryId(),
+      req.getTitle(),
+      req.getContent(),
+      req.getTagIds()
+    );
     return ResponseEntity.ok(postMapper.toDetailDto(post, auth.getName()));
   }
 
   @DeleteMapping("/{id}")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Delete post", description = "Delete a post")
+  @ApiResponse(responseCode = "200", description = "Post deleted")
   public void deletePost(@PathVariable Long id, Authentication auth) {
     postService.deletePost(id, auth.getName());
   }
 
   @PostMapping("/{id}/close")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Close post", description = "Close a post to prevent further replies")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Closed post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
   public PostSummaryDto close(@PathVariable Long id, Authentication auth) {
     return postMapper.toSummaryDto(postService.closePost(id, auth.getName()));
   }
 
   @PostMapping("/{id}/reopen")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Reopen post", description = "Reopen a closed post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reopened post",
+    content = @Content(schema = @Schema(implementation = PostSummaryDto.class))
+  )
   public PostSummaryDto reopen(@PathVariable Long id, Authentication auth) {
     return postMapper.toSummaryDto(postService.reopenPost(id, auth.getName()));
   }
 
   @GetMapping("/{id}")
+  @Operation(summary = "Get post", description = "Get post details by id")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Post detail",
+    content = @Content(schema = @Schema(implementation = PostDetailDto.class))
+  )
   public ResponseEntity<PostDetailDto> getPost(@PathVariable Long id, Authentication auth) {
     String viewer = auth != null ? auth.getName() : null;
     Post post = postService.viewPost(id, viewer);
@@ -83,129 +152,167 @@ public class PostController {
   }
 
   @PostMapping("/{id}/lottery/join")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Join lottery", description = "Join a lottery for the post")
+  @ApiResponse(responseCode = "200", description = "Joined lottery")
   public ResponseEntity<Void> joinLottery(@PathVariable Long id, Authentication auth) {
     postService.joinLottery(id, auth.getName());
     return ResponseEntity.ok().build();
   }
 
   @GetMapping("/{id}/poll/progress")
+  @Operation(summary = "Poll progress", description = "Get poll progress for a post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Poll progress",
+    content = @Content(schema = @Schema(implementation = PollDto.class))
+  )
   public ResponseEntity<PollDto> pollProgress(@PathVariable Long id) {
     return ResponseEntity.ok(postMapper.toSummaryDto(postService.getPoll(id)).getPoll());
   }
 
   @PostMapping("/{id}/poll/vote")
-    public ResponseEntity<Void> vote(@PathVariable Long id, @RequestParam("option") List<Integer> option, Authentication auth) {
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Vote poll", description = "Vote on a poll option")
+  @ApiResponse(responseCode = "200", description = "Vote recorded")
+  public ResponseEntity<Void> vote(
+    @PathVariable Long id,
+    @RequestParam("option") List<Integer> option,
+    Authentication auth
+  ) {
     postService.votePoll(id, auth.getName(), option);
     return ResponseEntity.ok().build();
   }
 
   @GetMapping
-    public List<PostSummaryDto> listPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
+  @Operation(summary = "List posts", description = "List posts by various filters")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  @Cacheable(
+    value = CachingConfig.POST_CACHE_NAME,
+    key = "new org.springframework.cache.interceptor.SimpleKey('default', #categoryId, #categoryIds, #tagId, #tagIds, #page, #pageSize)"
+  )
+  public List<PostSummaryDto> listPosts(
+    @RequestParam(value = "categoryId", required = false) Long categoryId,
     @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
     @RequestParam(value = "tagId", required = false) Long tagId,
     @RequestParam(value = "tagIds", required = false) List<Long> tagIds,
     @RequestParam(value = "page", required = false) Integer page,
     @RequestParam(value = "pageSize", required = false) Integer pageSize,
-                                   Authentication auth) {
+    Authentication auth
-        List<Long> ids = categoryIds;
+  ) {
-        if (categoryId != null) {
+    List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
-            ids = java.util.List.of(categoryId);
+    List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
-        }
+    // 只需要在请求的一开始统计一次
-        List<Long> tids = tagIds;
+    //        if (auth != null) {
-        if (tagId != null) {
+    //            userVisitService.recordVisit(auth.getName());
-            tids = java.util.List.of(tagId);
+    //        }
-        }
 
-        if (auth != null) {
+    return postService
-            userVisitService.recordVisit(auth.getName());
+      .defaultListPosts(ids, tids, page, pageSize)
-        }
+      .stream()
-
+      .map(postMapper::toSummaryDto)
-        boolean hasCategories = ids != null && !ids.isEmpty();
+      .collect(Collectors.toList());
-        boolean hasTags = tids != null && !tids.isEmpty();
-
-        if (hasCategories && hasTags) {
-            return postService.listPostsByCategoriesAndTags(ids, tids, page, pageSize)
-                    .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
-        }
-        if (hasTags) {
-            return postService.listPostsByTags(tids, page, pageSize)
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
-        }
-
-        return postService.listPostsByCategories(ids, page, pageSize)
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
   }
 
   @GetMapping("/ranking")
-    public List<PostSummaryDto> rankingPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
+  @Operation(summary = "Ranking posts", description = "List posts by view rankings")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Ranked posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  public List<PostSummaryDto> rankingPosts(
+    @RequestParam(value = "categoryId", required = false) Long categoryId,
     @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
     @RequestParam(value = "tagId", required = false) Long tagId,
     @RequestParam(value = "tagIds", required = false) List<Long> tagIds,
     @RequestParam(value = "page", required = false) Integer page,
     @RequestParam(value = "pageSize", required = false) Integer pageSize,
-                                      Authentication auth) {
+    Authentication auth
-        List<Long> ids = categoryIds;
+  ) {
-        if (categoryId != null) {
+    List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
-            ids = java.util.List.of(categoryId);
+    List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
-        }
+    // 只需要在请求的一开始统计一次
-        List<Long> tids = tagIds;
+    //        if (auth != null) {
-        if (tagId != null) {
+    //            userVisitService.recordVisit(auth.getName());
-            tids = java.util.List.of(tagId);
+    //        }
-        }
 
-        if (auth != null) {
+    return postService
-            userVisitService.recordVisit(auth.getName());
+      .listPostsByViews(ids, tids, page, pageSize)
-        }
+      .stream()
-
+      .map(postMapper::toSummaryDto)
-        return postService.listPostsByViews(ids, tids, page, pageSize)
+      .collect(Collectors.toList());
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
   }
 
   @GetMapping("/latest-reply")
-    public List<PostSummaryDto> latestReplyPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
+  @Operation(summary = "Latest reply posts", description = "List posts by latest replies")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Posts sorted by latest reply",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  @Cacheable(
+    value = CachingConfig.POST_CACHE_NAME,
+    key = "new org.springframework.cache.interceptor.SimpleKey('latest_reply', #categoryId, #categoryIds, #tagIds, #page, #pageSize)"
+  )
+  public List<PostSummaryDto> latestReplyPosts(
+    @RequestParam(value = "categoryId", required = false) Long categoryId,
     @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
     @RequestParam(value = "tagId", required = false) Long tagId,
     @RequestParam(value = "tagIds", required = false) List<Long> tagIds,
     @RequestParam(value = "page", required = false) Integer page,
     @RequestParam(value = "pageSize", required = false) Integer pageSize,
-                                          Authentication auth) {
+    Authentication auth
-        List<Long> ids = categoryIds;
+  ) {
-        if (categoryId != null) {
+    List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
-            ids = java.util.List.of(categoryId);
+    List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
-        }
+    // 只需要在请求的一开始统计一次
-        List<Long> tids = tagIds;
+    //        if (auth != null) {
-        if (tagId != null) {
+    //            userVisitService.recordVisit(auth.getName());
-            tids = java.util.List.of(tagId);
+    //        }
-        }
 
-        if (auth != null) {
+    List<Post> posts = postService.listPostsByLatestReply(ids, tids, page, pageSize);
-            userVisitService.recordVisit(auth.getName());
+    return posts.stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
-        }
-
-        return postService.listPostsByLatestReply(ids, tids, page, pageSize)
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
   }
 
   @GetMapping("/featured")
-    public List<PostSummaryDto> featuredPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
+  @Operation(summary = "Featured posts", description = "List featured posts")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Featured posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  public List<PostSummaryDto> featuredPosts(
+    @RequestParam(value = "categoryId", required = false) Long categoryId,
     @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
     @RequestParam(value = "tagId", required = false) Long tagId,
     @RequestParam(value = "tagIds", required = false) List<Long> tagIds,
     @RequestParam(value = "page", required = false) Integer page,
     @RequestParam(value = "pageSize", required = false) Integer pageSize,
-                                       Authentication auth) {
+    Authentication auth
-        List<Long> ids = categoryIds;
+  ) {
-        if (categoryId != null) {
+    List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
-            ids = java.util.List.of(categoryId);
+    List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
-        }
+    // 只需要在请求的一开始统计一次
-        List<Long> tids = tagIds;
+    //        if (auth != null) {
-        if (tagId != null) {
+    //            userVisitService.recordVisit(auth.getName());
-            tids = java.util.List.of(tagId);
+    //        }
-        }
+    return postService
-        if (auth != null) {
+      .listFeaturedPosts(ids, tids, page, pageSize)
-            userVisitService.recordVisit(auth.getName());
+      .stream()
-        }
+      .map(postMapper::toSummaryDto)
-        return postService.listFeaturedPosts(ids, tids, page, pageSize)
+      .collect(Collectors.toList());
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
   }
 }

backend/src/main/java/com/openisle/controller/PushSubscriptionController.java

@@ -3,6 +3,11 @@ package com.openisle.controller;
 import com.openisle.dto.PushPublicKeyDto;
 import com.openisle.dto.PushSubscriptionRequest;
 import com.openisle.service.PushSubscriptionService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.security.core.Authentication;
@@ -12,11 +17,19 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api/push")
 @RequiredArgsConstructor
 public class PushSubscriptionController {
+
   private final PushSubscriptionService pushSubscriptionService;
+
   @Value("${app.webpush.public-key}")
   private String publicKey;
 
   @GetMapping("/public-key")
+  @Operation(summary = "Get public key", description = "Retrieve web push public key")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Public key",
+    content = @Content(schema = @Schema(implementation = PushPublicKeyDto.class))
+  )
   public PushPublicKeyDto getPublicKey() {
     PushPublicKeyDto r = new PushPublicKeyDto();
     r.setKey(publicKey);
@@ -24,7 +37,15 @@ public class PushSubscriptionController {
   }
 
   @PostMapping("/subscribe")
+  @Operation(summary = "Subscribe", description = "Subscribe to push notifications")
+  @ApiResponse(responseCode = "200", description = "Subscribed")
+  @SecurityRequirement(name = "JWT")
   public void subscribe(@RequestBody PushSubscriptionRequest req, Authentication auth) {
-        pushSubscriptionService.saveSubscription(auth.getName(), req.getEndpoint(), req.getP256dh(), req.getAuth());
+    pushSubscriptionService.saveSubscription(
+      auth.getName(),
+      req.getEndpoint(),
+      req.getP256dh(),
+      req.getAuth()
+    );
   }
 }

backend/src/main/java/com/openisle/controller/ReactionController.java

@@ -8,6 +8,11 @@ import com.openisle.model.ReactionType;
 import com.openisle.service.LevelService;
 import com.openisle.service.PointService;
 import com.openisle.service.ReactionService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
@@ -17,6 +22,7 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api")
 @RequiredArgsConstructor
 public class ReactionController {
+
   private final ReactionService reactionService;
   private final LevelService levelService;
   private final ReactionMapper reactionMapper;
@@ -26,14 +32,29 @@ public class ReactionController {
    * Get all available reaction types.
    */
   @GetMapping("/reaction-types")
+  @Operation(summary = "List reaction types", description = "Get all available reaction types")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reaction types",
+    content = @Content(schema = @Schema(implementation = ReactionType[].class))
+  )
   public ReactionType[] listReactionTypes() {
     return ReactionType.values();
   }
 
   @PostMapping("/posts/{postId}/reactions")
-    public ResponseEntity<ReactionDto> reactToPost(@PathVariable Long postId,
+  @Operation(summary = "React to post", description = "React to a post")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reaction result",
+    content = @Content(schema = @Schema(implementation = ReactionDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<ReactionDto> reactToPost(
+    @PathVariable Long postId,
     @RequestBody ReactionRequest req,
-                                                   Authentication auth) {
+    Authentication auth
+  ) {
     Reaction reaction = reactionService.reactToPost(auth.getName(), postId, req.getType());
     if (reaction == null) {
       pointService.deductForReactionOfPost(auth.getName(), postId);
@@ -46,9 +67,18 @@ public class ReactionController {
   }
 
   @PostMapping("/comments/{commentId}/reactions")
-    public ResponseEntity<ReactionDto> reactToComment(@PathVariable Long commentId,
+  @Operation(summary = "React to comment", description = "React to a comment")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reaction result",
+    content = @Content(schema = @Schema(implementation = ReactionDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<ReactionDto> reactToComment(
+    @PathVariable Long commentId,
     @RequestBody ReactionRequest req,
-                                                      Authentication auth) {
+    Authentication auth
+  ) {
     Reaction reaction = reactionService.reactToComment(auth.getName(), commentId, req.getType());
     if (reaction == null) {
       pointService.deductForReactionOfComment(auth.getName(), commentId);
@@ -61,9 +91,18 @@ public class ReactionController {
   }
 
   @PostMapping("/messages/{messageId}/reactions")
-    public ResponseEntity<ReactionDto> reactToMessage(@PathVariable Long messageId,
+  @Operation(summary = "React to message", description = "React to a message")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Reaction result",
+    content = @Content(schema = @Schema(implementation = ReactionDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public ResponseEntity<ReactionDto> reactToMessage(
+    @PathVariable Long messageId,
     @RequestBody ReactionRequest req,
-                                                      Authentication auth) {
+    Authentication auth
+  ) {
     Reaction reaction = reactionService.reactToMessage(auth.getName(), messageId, req.getType());
     if (reaction == null) {
       return ResponseEntity.noContent().build();

backend/src/main/java/com/openisle/controller/RssController.java

@@ -1,10 +1,28 @@
 package com.openisle.controller;
 
-import com.openisle.model.Post;
 import com.openisle.model.Comment;
 import com.openisle.model.CommentSort;
-import com.openisle.service.PostService;
+import com.openisle.model.Post;
 import com.openisle.service.CommentService;
+import com.openisle.service.PostService;
+import com.vladsch.flexmark.ext.autolink.AutolinkExtension;
+import com.vladsch.flexmark.ext.gfm.strikethrough.StrikethroughExtension;
+import com.vladsch.flexmark.ext.gfm.tasklist.TaskListExtension;
+import com.vladsch.flexmark.ext.tables.TablesExtension;
+import com.vladsch.flexmark.html.HtmlRenderer;
+import com.vladsch.flexmark.parser.Parser;
+import com.vladsch.flexmark.util.data.MutableDataSet;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import java.net.URI;
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import lombok.RequiredArgsConstructor;
 import org.jsoup.Jsoup;
 import org.jsoup.nodes.Document;
@@ -14,25 +32,10 @@ import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 
-import com.vladsch.flexmark.ext.autolink.AutolinkExtension;
-import com.vladsch.flexmark.ext.tables.TablesExtension;
-import com.vladsch.flexmark.ext.gfm.strikethrough.StrikethroughExtension;
-import com.vladsch.flexmark.ext.gfm.tasklist.TaskListExtension;
-import com.vladsch.flexmark.html.HtmlRenderer;
-import com.vladsch.flexmark.parser.Parser;
-import com.vladsch.flexmark.util.data.MutableDataSet;
-
-import java.net.URI;
-import java.time.ZoneId;
-import java.time.ZonedDateTime;
-import java.time.format.DateTimeFormatter;
-import java.util.*;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-
 @RestController
 @RequiredArgsConstructor
 public class RssController {
+
   private final PostService postService;
   private final CommentService commentService;
 
@@ -41,21 +44,27 @@ public class RssController {
 
   // 兼容 Markdown/HTML 两类图片写法（用于 enclosure）
   private static final Pattern MD_IMAGE = Pattern.compile("!\\[[^\\]]*\\]\\(([^)]+)\\)");
-    private static final Pattern HTML_IMAGE = Pattern.compile("<BaseImage[^>]+src=[\"']?([^\"'>]+)[\"']?[^>]*>");
+  private static final Pattern HTML_IMAGE = Pattern.compile(
+    "<BaseImage[^>]+src=[\"']?([^\"'>]+)[\"']?[^>]*>"
+  );
 
   private static final DateTimeFormatter RFC1123 = DateTimeFormatter.RFC_1123_DATE_TIME;
 
   // flexmark：Markdown -> HTML
   private static final Parser MD_PARSER;
   private static final HtmlRenderer MD_RENDERER;
+
   static {
     MutableDataSet opts = new MutableDataSet();
-        opts.set(Parser.EXTENSIONS, Arrays.asList(
+    opts.set(
+      Parser.EXTENSIONS,
+      Arrays.asList(
         TablesExtension.create(),
         AutolinkExtension.create(),
         StrikethroughExtension.create(),
         TaskListExtension.create()
-        ));
+      )
+    );
     // 允许内联 HTML（下游再做 sanitize）
     opts.set(Parser.HTML_BLOCK_PARSER, true);
     MD_PARSER = Parser.builder(opts).build();
@@ -63,6 +72,12 @@ public class RssController {
   }
 
   @GetMapping(value = "/api/rss", produces = "application/rss+xml;charset=UTF-8")
+  @Operation(summary = "RSS feed", description = "Generate RSS feed for latest posts")
+  @ApiResponse(
+    responseCode = "200",
+    description = "RSS XML",
+    content = @Content(schema = @Schema(implementation = String.class))
+  )
   public String feed() {
     // 建议 20；你现在是 10，这里保留你的 10
     List<Post> posts = postService.listLatestRssPosts(10);
@@ -75,7 +90,8 @@ public class RssController {
     elem(sb, "title", cdata("OpenIsle RSS"));
     elem(sb, "link", base + "/");
     elem(sb, "description", cdata("Latest posts"));
-        ZonedDateTime updated = posts.stream()
+    ZonedDateTime updated = posts
+      .stream()
       .map(p -> p.getCreatedAt().atZone(ZoneId.systemDefault()))
       .max(Comparator.naturalOrder())
       .orElse(ZonedDateTime.now());
@@ -108,8 +124,10 @@ public class RssController {
       }
 
       // 6) 构造优雅的附加区块（原文链接 + 精选评论），编入 <content:encoded>
-            List<Comment> topComments = commentService
+      List<Comment> topComments = commentService.getCommentsForPost(
-                    .getCommentsForPost(p.getId(), CommentSort.MOST_INTERACTIONS);
+        p.getId(),
+        CommentSort.MOST_INTERACTIONS
+      );
       topComments = topComments.subList(0, Math.min(10, topComments.size()));
       String footerHtml = buildFooterHtml(base, link, topComments);
 
@@ -121,14 +139,19 @@ public class RssController {
       // 摘要
       elem(sb, "description", cdata(plain));
       // 全文（HTML）：正文 + 优雅的 Markdown 区块（已转 HTML）
-            sb.append("<content:encoded><![CDATA[")
+      sb
+        .append("<content:encoded><![CDATA[")
         .append(absHtml)
         .append(footerHtml)
         .append("]]></content:encoded>");
       // 首图 enclosure（图片类型）
       if (enclosure != null) {
-                sb.append("<enclosure url=\"").append(escapeXml(enclosure)).append("\" type=\"")
+        sb
-                        .append(getMimeType(enclosure)).append("\" />");
+          .append("<enclosure url=\"")
+          .append(escapeXml(enclosure))
+          .append("\" type=\"")
+          .append(getMimeType(enclosure))
+          .append("\" />");
       }
       sb.append("</item>");
     }
@@ -150,10 +173,26 @@ public class RssController {
     if (html == null) return "";
     Safelist wl = Safelist.relaxed()
       .addTags(
-                        "pre","code","figure","figcaption","picture","source",
+        "pre",
-                        "table","thead","tbody","tr","th","td",
+        "code",
-                        "h1","h2","h3","h4","h5","h6",
+        "figure",
-                        "hr","blockquote"
+        "figcaption",
+        "picture",
+        "source",
+        "table",
+        "thead",
+        "tbody",
+        "tr",
+        "th",
+        "td",
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "hr",
+        "blockquote"
       )
       .addAttributes("a", "href", "title", "target", "rel")
       .addAttributes("img", "src", "alt", "title", "width", "height")
@@ -269,15 +308,24 @@ public class RssController {
    * 将“原文链接 + 精选评论（最多 10 条）”以优雅的 Markdown 形式渲染为 HTML，
    * 并做 sanitize + 绝对化，然后拼入 content:encoded 尾部。
    */
-    private static String buildFooterHtml(String baseUrl, String originalLink, List<Comment> topComments) {
+  private static String buildFooterHtml(
+    String baseUrl,
+    String originalLink,
+    List<Comment> topComments
+  ) {
     StringBuilder md = new StringBuilder(256);
 
     // 分割线
     md.append("\n\n---\n\n");
 
     // 原文链接（强调 + 可点击）
-        md.append("**原文链接：** ")
+    md
-                .append("[").append(originalLink).append("](").append(originalLink).append(")")
+      .append("**原文链接：** ")
+      .append("[")
+      .append(originalLink)
+      .append("](")
+      .append(originalLink)
+      .append(")")
       .append("\n\n");
 
     // 精选评论（仅当有评论时展示）
@@ -334,8 +382,12 @@ public class RssController {
 
   private static String escapeXml(String s) {
     if (s == null) return "";
-        return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    return s
-                .replace("\"", "&quot;").replace("'", "&apos;");
+      .replace("&", "&amp;")
+      .replace("<", "&lt;")
+      .replace(">", "&gt;")
+      .replace("\"", "&quot;")
+      .replace("'", "&apos;");
   }
 
   private static String trimTrailingSlash(String s) {
@@ -348,5 +400,7 @@ public class RssController {
     return s.endsWith("/") ? s : s + "/";
   }
 
-    private static String nullSafe(String s) { return s == null ? "" : s; }
+  private static String nullSafe(String s) {
+    return s == null ? "" : s;
+  }
 }

backend/src/main/java/com/openisle/controller/SearchController.java

@@ -6,54 +6,107 @@ import com.openisle.dto.UserDto;
 import com.openisle.mapper.PostMapper;
 import com.openisle.mapper.UserMapper;
 import com.openisle.service.SearchService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import java.util.List;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
 @RestController
 @RequestMapping("/api/search")
 @RequiredArgsConstructor
 public class SearchController {
+
   private final SearchService searchService;
   private final UserMapper userMapper;
   private final PostMapper postMapper;
 
   @GetMapping("/users")
+  @Operation(summary = "Search users", description = "Search users by keyword")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of users",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class)))
+  )
   public List<UserDto> searchUsers(@RequestParam String keyword) {
-        return searchService.searchUsers(keyword).stream()
+    return searchService
+      .searchUsers(keyword)
+      .stream()
       .map(userMapper::toDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/posts")
+  @Operation(summary = "Search posts", description = "Search posts by keyword")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
   public List<PostSummaryDto> searchPosts(@RequestParam String keyword) {
-        return searchService.searchPosts(keyword).stream()
+    return searchService
+      .searchPosts(keyword)
+      .stream()
       .map(postMapper::toSummaryDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/posts/content")
+  @Operation(summary = "Search posts by content", description = "Search posts by content keyword")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
   public List<PostSummaryDto> searchPostsByContent(@RequestParam String keyword) {
-        return searchService.searchPostsByContent(keyword).stream()
+    return searchService
+      .searchPostsByContent(keyword)
+      .stream()
       .map(postMapper::toSummaryDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/posts/title")
+  @Operation(summary = "Search posts by title", description = "Search posts by title keyword")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
   public List<PostSummaryDto> searchPostsByTitle(@RequestParam String keyword) {
-        return searchService.searchPostsByTitle(keyword).stream()
+    return searchService
+      .searchPostsByTitle(keyword)
+      .stream()
       .map(postMapper::toSummaryDto)
       .collect(Collectors.toList());
   }
 
   @GetMapping("/global")
+  @Operation(summary = "Global search", description = "Search users and posts globally")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Search results",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = SearchResultDto.class))
+    )
+  )
   public List<SearchResultDto> global(@RequestParam String keyword) {
-        return searchService.globalSearch(keyword).stream()
+    return searchService
+      .globalSearch(keyword)
+      .stream()
       .map(r -> {
         SearchResultDto dto = new SearchResultDto();
         dto.setType(r.type());

backend/src/main/java/com/openisle/controller/SitemapController.java

@@ -3,6 +3,11 @@ package com.openisle.controller;
 import com.openisle.model.Post;
 import com.openisle.model.PostStatus;
 import com.openisle.repository.PostRepository;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.MediaType;
@@ -11,8 +16,6 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
-import java.util.List;
-
 /**
  * Controller for dynamic sitemap generation.
  */
@@ -20,12 +23,19 @@ import java.util.List;
 @RequiredArgsConstructor
 @RequestMapping("/api")
 public class SitemapController {
+
   private final PostRepository postRepository;
 
   @Value("${app.website-url}")
   private String websiteUrl;
 
   @GetMapping(value = "/sitemap.xml", produces = MediaType.APPLICATION_XML_VALUE)
+  @Operation(summary = "Sitemap", description = "Generate sitemap xml")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Sitemap xml",
+    content = @Content(schema = @Schema(implementation = String.class))
+  )
   public ResponseEntity<String> sitemap() {
     List<Post> posts = postRepository.findByStatus(PostStatus.PUBLISHED);
 
@@ -33,23 +43,15 @@ public class SitemapController {
     body.append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
     body.append("<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n");
 
-        List<String> staticRoutes = List.of(
+    List<String> staticRoutes = List.of("/", "/about", "/activities", "/login", "/signup");
-                "/",
-                "/about",
-                "/activities",
-                "/login",
-                "/signup"
-        );
 
     for (String path : staticRoutes) {
-            body.append("  <url><loc>")
+      body.append("  <url><loc>").append(websiteUrl).append(path).append("</loc></url>\n");
-                .append(websiteUrl)
-                .append(path)
-                .append("</loc></url>\n");
     }
 
     for (Post p : posts) {
-            body.append("  <url>\n")
+      body
+        .append("  <url>\n")
         .append("    <loc>")
         .append(websiteUrl)
         .append("/posts/")
@@ -62,8 +64,6 @@ public class SitemapController {
     }
 
     body.append("</urlset>");
-        return ResponseEntity.ok()
+    return ResponseEntity.ok().contentType(MediaType.APPLICATION_XML).body(body.toString());
-                .contentType(MediaType.APPLICATION_XML)
-                .body(body.toString());
   }
 }

backend/src/main/java/com/openisle/controller/StatController.java

@@ -1,7 +1,15 @@
 package com.openisle.controller;
 
-import com.openisle.service.UserVisitService;
 import com.openisle.service.StatService;
+import com.openisle.service.UserVisitService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Map;
 import lombok.RequiredArgsConstructor;
 import org.springframework.format.annotation.DateTimeFormat;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -9,77 +17,111 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-import java.time.LocalDate;
-import java.util.List;
-import java.util.Map;
-
 @RestController
 @RequestMapping("/api/stats")
 @RequiredArgsConstructor
 public class StatController {
+
   private final UserVisitService userVisitService;
   private final StatService statService;
 
   @GetMapping("/dau")
-    public Map<String, Long> dau(@RequestParam(value = "date", required = false)
+  @Operation(summary = "Daily active users", description = "Get daily active user count")
-                                 @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "DAU count",
+    content = @Content(schema = @Schema(implementation = java.util.Map.class))
+  )
+  public Map<String, Long> dau(
+    @RequestParam(value = "date", required = false) @DateTimeFormat(
+      iso = DateTimeFormat.ISO.DATE
+    ) LocalDate date
+  ) {
     long count = userVisitService.countDau(date);
     return Map.of("dau", count);
   }
 
   @GetMapping("/dau-range")
-    public List<Map<String, Object>> dauRange(@RequestParam(value = "days", defaultValue = "30") int days) {
+  @Operation(summary = "DAU range", description = "Get daily active users over range of days")
+  @ApiResponse(
+    responseCode = "200",
+    description = "DAU data",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class)))
+  )
+  public List<Map<String, Object>> dauRange(
+    @RequestParam(value = "days", defaultValue = "30") int days
+  ) {
     if (days < 1) days = 1;
     LocalDate end = LocalDate.now();
     LocalDate start = end.minusDays(days - 1L);
     var data = userVisitService.countDauRange(start, end);
-        return data.entrySet().stream()
+    return data
-                .map(e -> Map.<String,Object>of(
+      .entrySet()
-                        "date",  e.getKey().toString(),
+      .stream()
-                        "value", e.getValue()
+      .map(e -> Map.<String, Object>of("date", e.getKey().toString(), "value", e.getValue()))
-                ))
       .toList();
   }
 
   @GetMapping("/new-users-range")
-    public List<Map<String, Object>> newUsersRange(@RequestParam(value = "days", defaultValue = "30") int days) {
+  @Operation(summary = "New users range", description = "Get new users over range of days")
+  @ApiResponse(
+    responseCode = "200",
+    description = "New user data",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class)))
+  )
+  public List<Map<String, Object>> newUsersRange(
+    @RequestParam(value = "days", defaultValue = "30") int days
+  ) {
     if (days < 1) days = 1;
     LocalDate end = LocalDate.now();
     LocalDate start = end.minusDays(days - 1L);
     var data = statService.countNewUsersRange(start, end);
-        return data.entrySet().stream()
+    return data
-                .map(e -> Map.<String,Object>of(
+      .entrySet()
-                        "date", e.getKey().toString(),
+      .stream()
-                        "value", e.getValue()
+      .map(e -> Map.<String, Object>of("date", e.getKey().toString(), "value", e.getValue()))
-                ))
       .toList();
   }
 
   @GetMapping("/posts-range")
-    public List<Map<String, Object>> postsRange(@RequestParam(value = "days", defaultValue = "30") int days) {
+  @Operation(summary = "Posts range", description = "Get posts count over range of days")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Post data",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class)))
+  )
+  public List<Map<String, Object>> postsRange(
+    @RequestParam(value = "days", defaultValue = "30") int days
+  ) {
     if (days < 1) days = 1;
     LocalDate end = LocalDate.now();
     LocalDate start = end.minusDays(days - 1L);
     var data = statService.countPostsRange(start, end);
-        return data.entrySet().stream()
+    return data
-                .map(e -> Map.<String,Object>of(
+      .entrySet()
-                        "date", e.getKey().toString(),
+      .stream()
-                        "value", e.getValue()
+      .map(e -> Map.<String, Object>of("date", e.getKey().toString(), "value", e.getValue()))
-                ))
       .toList();
   }
 
   @GetMapping("/comments-range")
-    public List<Map<String, Object>> commentsRange(@RequestParam(value = "days", defaultValue = "30") int days) {
+  @Operation(summary = "Comments range", description = "Get comments count over range of days")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Comment data",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class)))
+  )
+  public List<Map<String, Object>> commentsRange(
+    @RequestParam(value = "days", defaultValue = "30") int days
+  ) {
     if (days < 1) days = 1;
     LocalDate end = LocalDate.now();
     LocalDate start = end.minusDays(days - 1L);
     var data = statService.countCommentsRange(start, end);
-        return data.entrySet().stream()
+    return data
-                .map(e -> Map.<String,Object>of(
+      .entrySet()
-                        "date", e.getKey().toString(),
+      .stream()
-                        "value", e.getValue()
+      .map(e -> Map.<String, Object>of("date", e.getKey().toString(), "value", e.getValue()))
-                ))
       .toList();
   }
 }

backend/src/main/java/com/openisle/controller/SubscriptionController.java

@@ -1,6 +1,9 @@
 package com.openisle.controller;
 
 import com.openisle.service.SubscriptionService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
@@ -10,34 +13,53 @@ import org.springframework.web.bind.annotation.*;
 @RequestMapping("/api/subscriptions")
 @RequiredArgsConstructor
 public class SubscriptionController {
+
   private final SubscriptionService subscriptionService;
 
   @PostMapping("/posts/{postId}")
+  @Operation(summary = "Subscribe post", description = "Subscribe to a post")
+  @ApiResponse(responseCode = "200", description = "Subscribed")
+  @SecurityRequirement(name = "JWT")
   public void subscribePost(@PathVariable Long postId, Authentication auth) {
     subscriptionService.subscribePost(auth.getName(), postId);
   }
 
   @DeleteMapping("/posts/{postId}")
+  @Operation(summary = "Unsubscribe post", description = "Unsubscribe from a post")
+  @ApiResponse(responseCode = "200", description = "Unsubscribed")
+  @SecurityRequirement(name = "JWT")
   public void unsubscribePost(@PathVariable Long postId, Authentication auth) {
     subscriptionService.unsubscribePost(auth.getName(), postId);
   }
 
   @PostMapping("/comments/{commentId}")
+  @Operation(summary = "Subscribe comment", description = "Subscribe to a comment")
+  @ApiResponse(responseCode = "200", description = "Subscribed")
+  @SecurityRequirement(name = "JWT")
   public void subscribeComment(@PathVariable Long commentId, Authentication auth) {
     subscriptionService.subscribeComment(auth.getName(), commentId);
   }
 
   @DeleteMapping("/comments/{commentId}")
+  @Operation(summary = "Unsubscribe comment", description = "Unsubscribe from a comment")
+  @ApiResponse(responseCode = "200", description = "Unsubscribed")
+  @SecurityRequirement(name = "JWT")
   public void unsubscribeComment(@PathVariable Long commentId, Authentication auth) {
     subscriptionService.unsubscribeComment(auth.getName(), commentId);
   }
 
   @PostMapping("/users/{username}")
+  @Operation(summary = "Subscribe user", description = "Subscribe to a user")
+  @ApiResponse(responseCode = "200", description = "Subscribed")
+  @SecurityRequirement(name = "JWT")
   public void subscribeUser(@PathVariable String username, Authentication auth) {
     subscriptionService.subscribeUser(auth.getName(), username);
   }
 
   @DeleteMapping("/users/{username}")
+  @Operation(summary = "Unsubscribe user", description = "Unsubscribe from a user")
+  @ApiResponse(responseCode = "200", description = "Unsubscribed")
+  @SecurityRequirement(name = "JWT")
   public void unsubscribeUser(@PathVariable String username, Authentication auth) {
     subscriptionService.unsubscribeUser(auth.getName(), username);
   }

backend/src/main/java/com/openisle/controller/TagController.java

@@ -11,17 +11,23 @@ import com.openisle.model.Tag;
 import com.openisle.repository.UserRepository;
 import com.openisle.service.PostService;
 import com.openisle.service.TagService;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
-
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/api/tags")
 @RequiredArgsConstructor
 public class TagController {
+
   private final TagService tagService;
   private final PostService postService;
   private final UserRepository userRepository;
@@ -29,7 +35,17 @@ public class TagController {
   private final TagMapper tagMapper;
 
   @PostMapping
-    public TagDto create(@RequestBody TagRequest req, org.springframework.security.core.Authentication auth) {
+  @Operation(summary = "Create tag", description = "Create a new tag")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Created tag",
+    content = @Content(schema = @Schema(implementation = TagDto.class))
+  )
+  @SecurityRequirement(name = "JWT")
+  public TagDto create(
+    @RequestBody TagRequest req,
+    org.springframework.security.core.Authentication auth
+  ) {
     boolean approved = true;
     if (postService.getPublishMode() == PublishMode.REVIEW && auth != null) {
       com.openisle.model.User user = userRepository.findByUsername(auth.getName()).orElseThrow();
@@ -43,30 +59,54 @@ public class TagController {
       req.getIcon(),
       req.getSmallIcon(),
       approved,
-                auth != null ? auth.getName() : null);
+      auth != null ? auth.getName() : null
+    );
     long count = postService.countPostsByTag(tag.getId());
     return tagMapper.toDto(tag, count);
   }
 
   @PutMapping("/{id}")
+  @Operation(summary = "Update tag", description = "Update an existing tag")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Updated tag",
+    content = @Content(schema = @Schema(implementation = TagDto.class))
+  )
   public TagDto update(@PathVariable Long id, @RequestBody TagRequest req) {
-        Tag tag = tagService.updateTag(id, req.getName(), req.getDescription(), req.getIcon(), req.getSmallIcon());
+    Tag tag = tagService.updateTag(
+      id,
+      req.getName(),
+      req.getDescription(),
+      req.getIcon(),
+      req.getSmallIcon()
+    );
     long count = postService.countPostsByTag(tag.getId());
     return tagMapper.toDto(tag, count);
   }
 
   @DeleteMapping("/{id}")
+  @Operation(summary = "Delete tag", description = "Delete a tag by id")
+  @ApiResponse(responseCode = "200", description = "Tag deleted")
   public void delete(@PathVariable Long id) {
     tagService.deleteTag(id);
   }
 
   @GetMapping
-    public List<TagDto> list(@RequestParam(value = "keyword", required = false) String keyword,
+  @Operation(summary = "List tags", description = "List tags with optional keyword")
-                             @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of tags",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class)))
+  )
+  public List<TagDto> list(
+    @RequestParam(value = "keyword", required = false) String keyword,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     List<Tag> tags = tagService.searchTags(keyword);
     List<Long> tagIds = tags.stream().map(Tag::getId).toList();
     Map<Long, Long> postCntByTagIds = postService.countPostsByTagIds(tagIds);
-        List<TagDto> dtos = tags.stream()
+    List<TagDto> dtos = tags
+      .stream()
       .map(t -> tagMapper.toDto(t, postCntByTagIds.getOrDefault(t.getId(), 0L)))
       .sorted((a, b) -> Long.compare(b.getCount(), a.getCount()))
       .collect(Collectors.toList());
@@ -77,6 +117,12 @@ public class TagController {
   }
 
   @GetMapping("/{id}")
+  @Operation(summary = "Get tag", description = "Get tag by id")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Tag detail",
+    content = @Content(schema = @Schema(implementation = TagDto.class))
+  )
   public TagDto get(@PathVariable Long id) {
     Tag tag = tagService.getTag(id);
     long count = postService.countPostsByTag(tag.getId());
@@ -84,10 +130,21 @@ public class TagController {
   }
 
   @GetMapping("/{id}/posts")
-    public List<PostSummaryDto> listPostsByTag(@PathVariable Long id,
+  @Operation(summary = "List posts by tag", description = "Get posts with specific tag")
+  @ApiResponse(
+    responseCode = "200",
+    description = "List of posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  public List<PostSummaryDto> listPostsByTag(
+    @PathVariable Long id,
     @RequestParam(value = "page", required = false) Integer page,
-                                               @RequestParam(value = "pageSize", required = false) Integer pageSize) {
+    @RequestParam(value = "pageSize", required = false) Integer pageSize
-        return postService.listPostsByTags(java.util.List.of(id), page, pageSize)
+  ) {
+    return postService
+      .listPostsByTags(java.util.List.of(id), page, pageSize)
       .stream()
       .map(postMapper::toSummaryDto)
       .collect(Collectors.toList());

backend/src/main/java/com/openisle/controller/UploadController.java

@@ -1,23 +1,27 @@
 package com.openisle.controller;
 
 import com.openisle.service.ImageUploader;
-import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Operation;
-import org.springframework.beans.factory.annotation.Value;
+import io.swagger.v3.oas.annotations.media.Content;
-import org.springframework.http.ResponseEntity;
+import io.swagger.v3.oas.annotations.media.Schema;
-import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
-import org.springframework.web.multipart.MultipartFile;
-
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.net.URI;
 import java.net.URL;
 import java.net.URLConnection;
 import java.util.Map;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
 
 @RestController
 @RequestMapping("/api/upload")
 @RequiredArgsConstructor
 public class UploadController {
+
   private final ImageUploader imageUploader;
 
   @Value("${app.upload.check-type:true}")
@@ -27,8 +31,17 @@ public class UploadController {
   private long maxUploadSize;
 
   @PostMapping
+  @Operation(summary = "Upload file", description = "Upload image file")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Upload result",
+    content = @Content(schema = @Schema(implementation = java.util.Map.class))
+  )
   public ResponseEntity<?> upload(@RequestParam("file") MultipartFile file) {
-        if (checkImageType && (file.getContentType() == null || !file.getContentType().startsWith("image/"))) {
+    if (
+      checkImageType &&
+      (file.getContentType() == null || !file.getContentType().startsWith("image/"))
+    ) {
       return ResponseEntity.badRequest().body(Map.of("code", 1, "msg", "File is not an image"));
     }
     if (file.getSize() > maxUploadSize) {
@@ -40,14 +53,16 @@ public class UploadController {
     } catch (IOException e) {
       return ResponseEntity.internalServerError().body(Map.of("code", 3, "msg", "Upload failed"));
     }
-        return ResponseEntity.ok(Map.of(
+    return ResponseEntity.ok(Map.of("code", 0, "msg", "ok", "data", Map.of("url", url)));
-                "code", 0,
-                "msg", "ok",
-                "data", Map.of("url", url)
-        ));
   }
 
   @PostMapping("/url")
+  @Operation(summary = "Upload from URL", description = "Upload image from remote URL")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Upload result",
+    content = @Content(schema = @Schema(implementation = java.util.Map.class))
+  )
   public ResponseEntity<?> uploadUrl(@RequestBody Map<String, String> body) {
     String link = body.get("url");
     if (link == null || link.isBlank()) {
@@ -65,17 +80,19 @@ public class UploadController {
         return ResponseEntity.badRequest().body(Map.of("code", 1, "msg", "File is not an image"));
       }
       String url = imageUploader.upload(data, filename).join();
-            return ResponseEntity.ok(Map.of(
+      return ResponseEntity.ok(Map.of("code", 0, "msg", "ok", "data", Map.of("url", url)));
-                    "code", 0,
-                    "msg", "ok",
-                    "data", Map.of("url", url)
-            ));
     } catch (Exception e) {
       return ResponseEntity.internalServerError().body(Map.of("code", 3, "msg", "Upload failed"));
     }
   }
 
   @GetMapping("/presign")
+  @Operation(summary = "Presign upload", description = "Get presigned upload URL")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Presigned URL",
+    content = @Content(schema = @Schema(implementation = java.util.Map.class))
+  )
   public java.util.Map<String, String> presign(@RequestParam("filename") String filename) {
     return imageUploader.presignUpload(filename);
   }

backend/src/main/java/com/openisle/controller/UserController.java

@@ -6,6 +6,14 @@ import com.openisle.mapper.TagMapper;
 import com.openisle.mapper.UserMapper;
 import com.openisle.model.User;
 import com.openisle.service.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import java.io.IOException;
+import java.util.Map;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
@@ -13,13 +21,11 @@ import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
 
-import java.io.IOException;
-import java.util.Map;
-
 @RestController
 @RequestMapping("/api/users")
 @RequiredArgsConstructor
 public class UserController {
+
   private final UserService userService;
   private final ImageUploader imageUploader;
   private final PostService postService;
@@ -48,15 +54,34 @@ public class UserController {
   private int defaultTagsLimit;
 
   @GetMapping("/me")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Current user", description = "Get current authenticated user information")
+  @ApiResponse(
+    responseCode = "200",
+    description = "User detail",
+    content = @Content(schema = @Schema(implementation = UserDto.class))
+  )
   public ResponseEntity<UserDto> me(Authentication auth) {
     User user = userService.findByUsername(auth.getName()).orElseThrow();
     return ResponseEntity.ok(userMapper.toDto(user, auth));
   }
 
   @PostMapping("/me/avatar")
-    public ResponseEntity<?> uploadAvatar(@RequestParam("file") MultipartFile file,
+  @SecurityRequirement(name = "JWT")
-                                          Authentication auth) {
+  @Operation(summary = "Upload avatar", description = "Upload avatar for current user")
-        if (checkImageType && (file.getContentType() == null || !file.getContentType().startsWith("image/"))) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Upload result",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
+  public ResponseEntity<?> uploadAvatar(
+    @RequestParam("file") MultipartFile file,
+    Authentication auth
+  ) {
+    if (
+      checkImageType &&
+      (file.getContentType() == null || !file.getContentType().startsWith("image/"))
+    ) {
       return ResponseEntity.badRequest().body(Map.of("error", "File is not an image"));
     }
     if (file.getSize() > maxUploadSize) {
@@ -73,87 +98,179 @@ public class UserController {
   }
 
   @PutMapping("/me")
-    public ResponseEntity<?> updateProfile(@RequestBody UpdateProfileDto dto,
+  @SecurityRequirement(name = "JWT")
-                                           Authentication auth) {
+  @Operation(summary = "Update profile", description = "Update current user's profile")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Updated profile",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
+  public ResponseEntity<?> updateProfile(@RequestBody UpdateProfileDto dto, Authentication auth) {
     User user = userService.updateProfile(auth.getName(), dto.getUsername(), dto.getIntroduction());
-        return ResponseEntity.ok(Map.of(
+    return ResponseEntity.ok(
-                "token", jwtService.generateToken(user.getUsername()),
+      Map.of(
-                "user", userMapper.toDto(user, auth)
+        "token",
-        ));
+        jwtService.generateToken(user.getUsername()),
+        "user",
+        userMapper.toDto(user, auth)
+      )
+    );
   }
 
+  // 这个方法似乎没有使用？
   @PostMapping("/me/signin")
+  @SecurityRequirement(name = "JWT")
+  @Operation(summary = "Daily sign in", description = "Sign in to receive rewards")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Sign in reward",
+    content = @Content(schema = @Schema(implementation = Map.class))
+  )
   public Map<String, Integer> signIn(Authentication auth) {
     int reward = levelService.awardForSignin(auth.getName());
     return Map.of("reward", reward);
   }
 
   @GetMapping("/{identifier}")
-    public ResponseEntity<UserDto> getUser(@PathVariable("identifier") String identifier,
+  @Operation(summary = "Get user", description = "Get user by identifier")
-                                           Authentication auth) {
+  @ApiResponse(
-        User user = userService.findByIdentifier(identifier).orElseThrow(() -> new NotFoundException("User not found"));
+    responseCode = "200",
+    description = "User detail",
+    content = @Content(schema = @Schema(implementation = UserDto.class))
+  )
+  public ResponseEntity<UserDto> getUser(
+    @PathVariable("identifier") String identifier,
+    Authentication auth
+  ) {
+    User user = userService
+      .findByIdentifier(identifier)
+      .orElseThrow(() -> new NotFoundException("User not found"));
     return ResponseEntity.ok(userMapper.toDto(user, auth));
   }
 
   @GetMapping("/{identifier}/posts")
-    public java.util.List<PostMetaDto> userPosts(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User posts", description = "Get recent posts by user")
-                                                 @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "User posts",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostMetaDto.class)))
+  )
+  public java.util.List<PostMetaDto> userPosts(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : defaultPostsLimit;
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return postService.getRecentPostsByUser(user.getUsername(), l).stream()
+    return postService
+      .getRecentPostsByUser(user.getUsername(), l)
+      .stream()
       .map(userMapper::toMetaDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/subscribed-posts")
-    public java.util.List<PostMetaDto> subscribedPosts(@PathVariable("identifier") String identifier,
+  @Operation(summary = "Subscribed posts", description = "Get posts the user subscribed to")
-                                                       @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Subscribed posts",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostMetaDto.class)))
+  )
+  public java.util.List<PostMetaDto> subscribedPosts(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : defaultPostsLimit;
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return subscriptionService.getSubscribedPosts(user.getUsername()).stream()
+    return subscriptionService
+      .getSubscribedPosts(user.getUsername())
+      .stream()
       .limit(l)
       .map(userMapper::toMetaDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/replies")
-    public java.util.List<CommentInfoDto> userReplies(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User replies", description = "Get recent replies by user")
-                                                      @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "User replies",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = CommentInfoDto.class))
+    )
+  )
+  public java.util.List<CommentInfoDto> userReplies(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : defaultRepliesLimit;
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return commentService.getRecentCommentsByUser(user.getUsername(), l).stream()
+    return commentService
+      .getRecentCommentsByUser(user.getUsername(), l)
+      .stream()
       .map(userMapper::toCommentInfoDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/hot-posts")
-    public java.util.List<PostMetaDto> hotPosts(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User hot posts", description = "Get most reacted posts by user")
-                                                @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Hot posts",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostMetaDto.class)))
+  )
+  public java.util.List<PostMetaDto> hotPosts(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : 10;
     User user = userService.findByIdentifier(identifier).orElseThrow();
     java.util.List<Long> ids = reactionService.topPostIds(user.getUsername(), l);
-        return postService.getPostsByIds(ids).stream()
+    return postService
+      .getPostsByIds(ids)
+      .stream()
       .map(userMapper::toMetaDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/hot-replies")
-    public java.util.List<CommentInfoDto> hotReplies(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User hot replies", description = "Get most reacted replies by user")
-                                                     @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Hot replies",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = CommentInfoDto.class))
+    )
+  )
+  public java.util.List<CommentInfoDto> hotReplies(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : 10;
     User user = userService.findByIdentifier(identifier).orElseThrow();
     java.util.List<Long> ids = reactionService.topCommentIds(user.getUsername(), l);
-        return commentService.getCommentsByIds(ids).stream()
+    return commentService
+      .getCommentsByIds(ids)
+      .stream()
       .map(userMapper::toCommentInfoDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/hot-tags")
-    public java.util.List<TagDto> hotTags(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User hot tags", description = "Get tags frequently used by user")
-                                          @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "Hot tags",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class)))
+  )
+  public java.util.List<TagDto> hotTags(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : 10;
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return tagService.getTagsByUser(user.getUsername()).stream()
+    return tagService
+      .getTagsByUser(user.getUsername())
+      .stream()
       .map(t -> tagMapper.toDto(t, postService.countPostsByTag(t.getId())))
       .sorted((a, b) -> Long.compare(b.getCount(), a.getCount()))
       .limit(l)
@@ -161,50 +278,96 @@ public class UserController {
   }
 
   @GetMapping("/{identifier}/tags")
-    public java.util.List<TagDto> userTags(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User tags", description = "Get recent tags used by user")
-                                           @RequestParam(value = "limit", required = false) Integer limit) {
+  @ApiResponse(
+    responseCode = "200",
+    description = "User tags",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class)))
+  )
+  public java.util.List<TagDto> userTags(
+    @PathVariable("identifier") String identifier,
+    @RequestParam(value = "limit", required = false) Integer limit
+  ) {
     int l = limit != null ? limit : defaultTagsLimit;
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return tagService.getRecentTagsByUser(user.getUsername(), l).stream()
+    return tagService
+      .getRecentTagsByUser(user.getUsername(), l)
+      .stream()
       .map(t -> tagMapper.toDto(t, postService.countPostsByTag(t.getId())))
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/following")
+  @Operation(summary = "Following users", description = "Get users that this user is following")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Following list",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class)))
+  )
   public java.util.List<UserDto> following(@PathVariable("identifier") String identifier) {
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return subscriptionService.getSubscribedUsers(user.getUsername()).stream()
+    return subscriptionService
+      .getSubscribedUsers(user.getUsername())
+      .stream()
       .map(userMapper::toDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/followers")
+  @Operation(summary = "Followers", description = "Get followers of this user")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Followers list",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class)))
+  )
   public java.util.List<UserDto> followers(@PathVariable("identifier") String identifier) {
     User user = userService.findByIdentifier(identifier).orElseThrow();
-        return subscriptionService.getSubscribers(user.getUsername()).stream()
+    return subscriptionService
+      .getSubscribers(user.getUsername())
+      .stream()
       .map(userMapper::toDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/admins")
+  @Operation(summary = "Admin users", description = "List administrator users")
+  @ApiResponse(
+    responseCode = "200",
+    description = "Admin users",
+    content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class)))
+  )
   public java.util.List<UserDto> admins() {
-        return userService.getAdmins().stream()
+    return userService
+      .getAdmins()
+      .stream()
       .map(userMapper::toDto)
       .collect(java.util.stream.Collectors.toList());
   }
 
   @GetMapping("/{identifier}/all")
-    public ResponseEntity<UserAggregateDto> userAggregate(@PathVariable("identifier") String identifier,
+  @Operation(summary = "User aggregate", description = "Get aggregate information for user")
+  @ApiResponse(
+    responseCode = "200",
+    description = "User aggregate",
+    content = @Content(schema = @Schema(implementation = UserAggregateDto.class))
+  )
+  public ResponseEntity<UserAggregateDto> userAggregate(
+    @PathVariable("identifier") String identifier,
     @RequestParam(value = "postsLimit", required = false) Integer postsLimit,
     @RequestParam(value = "repliesLimit", required = false) Integer repliesLimit,
-                                                          Authentication auth) {
+    Authentication auth
+  ) {
     User user = userService.findByIdentifier(identifier).orElseThrow();
     int pLimit = postsLimit != null ? postsLimit : defaultPostsLimit;
     int rLimit = repliesLimit != null ? repliesLimit : defaultRepliesLimit;
-        java.util.List<PostMetaDto> posts = postService.getRecentPostsByUser(user.getUsername(), pLimit).stream()
+    java.util.List<PostMetaDto> posts = postService
+      .getRecentPostsByUser(user.getUsername(), pLimit)
+      .stream()
       .map(userMapper::toMetaDto)
       .collect(java.util.stream.Collectors.toList());
-        java.util.List<CommentInfoDto> replies = commentService.getRecentCommentsByUser(user.getUsername(), rLimit).stream()
+    java.util.List<CommentInfoDto> replies = commentService
+      .getRecentCommentsByUser(user.getUsername(), rLimit)
+      .stream()
       .map(userMapper::toCommentInfoDto)
       .collect(java.util.stream.Collectors.toList());
     UserAggregateDto dto = new UserAggregateDto();

backend/src/main/java/com/openisle/dto/ActivityDto.java

@@ -1,15 +1,15 @@
 package com.openisle.dto;
 
 import com.openisle.model.ActivityType;
-import lombok.Data;
-
 import java.time.LocalDateTime;
+import lombok.Data;
 
 /**
  * DTO representing an activity without participant details.
  */
 @Data
 public class ActivityDto {
+
   private Long id;
   private String title;
   private String icon;

backend/src/main/java/com/openisle/dto/AuthorDto.java

@@ -1,16 +1,16 @@
 package com.openisle.dto;
 
-import lombok.Data;
 import com.openisle.model.MedalType;
+import lombok.Data;
 
 /**
  * DTO representing a post or comment author.
  */
 @Data
 public class AuthorDto {
+
   private Long id;
   private String username;
   private String avatar;
   private MedalType displayMedal;
 }
-

backend/src/main/java/com/openisle/dto/CategoryDto.java

@@ -7,6 +7,7 @@ import lombok.Data;
  */
 @Data
 public class CategoryDto {
+
   private Long id;
   private String name;
   private String description;
@@ -14,4 +15,3 @@ public class CategoryDto {
   private String smallIcon;
   private Long count;
 }
-

backend/src/main/java/com/openisle/dto/CategoryRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request body for creating or updating a category. */
 @Data
 public class CategoryRequest {
+
   private String name;
   private String description;
   private String icon;

backend/src/main/java/com/openisle/dto/ChannelDto.java

@@ -6,6 +6,7 @@ import lombok.Setter;
 @Getter
 @Setter
 public class ChannelDto {
+
   private Long id;
   private String name;
   private String description;

backend/src/main/java/com/openisle/dto/CommentDto.java

@@ -1,15 +1,15 @@
 package com.openisle.dto;
 
-import lombok.Data;
-
 import java.time.LocalDateTime;
 import java.util.List;
+import lombok.Data;
 
 /**
  * DTO representing a comment and its nested replies.
  */
 @Data
 public class CommentDto {
+
   private Long id;
   private String content;
   private LocalDateTime createdAt;
@@ -20,4 +20,3 @@ public class CommentDto {
   private int reward;
   private int pointReward;
 }
-

backend/src/main/java/com/openisle/dto/CommentInfoDto.java

@@ -1,12 +1,12 @@
 package com.openisle.dto;
 
-import lombok.Data;
-
 import java.time.LocalDateTime;
+import lombok.Data;
 
 /** DTO for comment information in user profiles. */
 @Data
 public class CommentInfoDto {
+
   private Long id;
   private String content;
   private LocalDateTime createdAt;

backend/src/main/java/com/openisle/dto/CommentMedalDto.java

@@ -6,6 +6,7 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class CommentMedalDto extends MedalDto {
+
   private long currentCommentCount;
   private long targetCommentCount;
 }

backend/src/main/java/com/openisle/dto/CommentRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request body for creating or replying to a comment. */
 @Data
 public class CommentRequest {
+
   private String content;
   private String captcha;
 }

backend/src/main/java/com/openisle/dto/ConfigDto.java

@@ -8,6 +8,7 @@ import lombok.Data;
 /** DTO for site configuration. */
 @Data
 public class ConfigDto {
+
   private PublishMode publishMode;
   private PasswordStrength passwordStrength;
   private Integer aiFormatLimit;

backend/src/main/java/com/openisle/dto/ContributorMedalDto.java

@@ -6,7 +6,7 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class ContributorMedalDto extends MedalDto {
+
   private long currentContributionLines;
   private long targetContributionLines;
 }
-

backend/src/main/java/com/openisle/dto/ConversationDetailDto.java

@@ -1,12 +1,12 @@
 package com.openisle.dto;
 
+import java.util.List;
 import lombok.Data;
 import org.springframework.data.domain.Page;
 
-import java.util.List;
-
 @Data
 public class ConversationDetailDto {
+
   private Long id;
   private String name;
   private boolean channel;

backend/src/main/java/com/openisle/dto/ConversationDto.java

@@ -1,14 +1,14 @@
 package com.openisle.dto;
 
-import lombok.Getter;
-import lombok.Setter;
-
 import java.time.LocalDateTime;
 import java.util.List;
+import lombok.Getter;
+import lombok.Setter;
 
 @Getter
 @Setter
 public class ConversationDto {
+
   private Long id;
   private String name;
   private boolean channel;

backend/src/main/java/com/openisle/dto/CreateConversationRequest.java

@@ -4,5 +4,6 @@ import lombok.Data;
 
 @Data
 public class CreateConversationRequest {
+
   private Long recipientId;
 }

backend/src/main/java/com/openisle/dto/CreateConversationResponse.java

@@ -8,5 +8,6 @@ import lombok.NoArgsConstructor;
 @AllArgsConstructor
 @NoArgsConstructor
 public class CreateConversationResponse {
+
   private Long conversationId;
 }

backend/src/main/java/com/openisle/dto/DiscordLoginRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request for Discord OAuth login. */
 @Data
 public class DiscordLoginRequest {
+
   private String code;
   private String redirectUri;
   private String inviteToken;

backend/src/main/java/com/openisle/dto/DraftDto.java

@@ -1,12 +1,12 @@
 package com.openisle.dto;
 
-import lombok.Data;
-
 import java.util.List;
+import lombok.Data;
 
 /** DTO representing a saved draft. */
 @Data
 public class DraftDto {
+
   private Long id;
   private String title;
   private String content;

backend/src/main/java/com/openisle/dto/DraftRequest.java

@@ -1,12 +1,12 @@
 package com.openisle.dto;
 
-import lombok.Data;
-
 import java.util.List;
+import lombok.Data;
 
 /** Request body for saving a draft. */
 @Data
 public class DraftRequest {
+
   private String title;
   private String content;
   private Long categoryId;

backend/src/main/java/com/openisle/dto/FeaturedMedalDto.java

@@ -6,7 +6,7 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class FeaturedMedalDto extends MedalDto {
+
   private long currentFeaturedCount;
   private long targetFeaturedCount;
 }
-

backend/src/main/java/com/openisle/dto/ForgotPasswordRequest.java

@@ -5,5 +5,6 @@ import lombok.Data;
 /** Request to trigger a forgot password email. */
 @Data
 public class ForgotPasswordRequest {
+
   private String email;
 }

backend/src/main/java/com/openisle/dto/GithubLoginRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request for GitHub OAuth login. */
 @Data
 public class GithubLoginRequest {
+
   private String code;
   private String redirectUri;
   private String inviteToken;

backend/src/main/java/com/openisle/dto/GoogleLoginRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request for Google OAuth login. */
 @Data
 public class GoogleLoginRequest {
+
   private String idToken;
   private String inviteToken;
 }

backend/src/main/java/com/openisle/dto/LoginRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request to login. */
 @Data
 public class LoginRequest {
+
   private String username;
   private String password;
   private String captcha;

backend/src/main/java/com/openisle/dto/LotteryDto.java

@@ -1,12 +1,13 @@
 package com.openisle.dto;
 
-import lombok.Data;
 import java.time.LocalDateTime;
 import java.util.List;
+import lombok.Data;
 
 /** Metadata for lottery posts. */
 @Data
 public class LotteryDto {
+
   private String prizeDescription;
   private String prizeIcon;
   private int prizeCount;

backend/src/main/java/com/openisle/dto/MakeReasonRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request to submit a reason (e.g., for moderation). */
 @Data
 public class MakeReasonRequest {
+
   private String token;
   private String reason;
 }

backend/src/main/java/com/openisle/dto/MedalDto.java

@@ -5,6 +5,7 @@ import lombok.Data;
 
 @Data
 public class MedalDto {
+
   private String icon;
   private String title;
   private String description;

backend/src/main/java/com/openisle/dto/MedalSelectRequest.java

@@ -5,5 +5,6 @@ import lombok.Data;
 
 @Data
 public class MedalSelectRequest {
+
   private MedalType type;
 }

backend/src/main/java/com/openisle/dto/MessageDto.java

@@ -1,11 +1,12 @@
 package com.openisle.dto;
 
-import lombok.Data;
 import java.time.LocalDateTime;
 import java.util.List;
+import lombok.Data;
 
 @Data
 public class MessageDto {
+
   private Long id;
   private String content;
   private UserSummaryDto sender;

backend/src/main/java/com/openisle/dto/MessageNotificationPayload.java

@@ -1,15 +1,15 @@
 package com.openisle.dto;
 
+import java.io.Serializable;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
-import java.io.Serializable;
-
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
 public class MessageNotificationPayload implements Serializable {
+
   private String targetUsername;
   private Object payload;
 }

backend/src/main/java/com/openisle/dto/MilkTeaInfoDto.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Info about the milk tea activity. */
 @Data
 public class MilkTeaInfoDto {
+
   private long redeemCount;
   private boolean ended;
 }

backend/src/main/java/com/openisle/dto/MilkTeaRedeemRequest.java

@@ -5,5 +5,6 @@ import lombok.Data;
 /** Request to redeem the milk tea activity. */
 @Data
 public class MilkTeaRedeemRequest {
+
   private String contact;
 }

backend/src/main/java/com/openisle/dto/NotificationDto.java

@@ -2,13 +2,13 @@ package com.openisle.dto;
 
 import com.openisle.model.NotificationType;
 import com.openisle.model.ReactionType;
-import lombok.Data;
-
 import java.time.LocalDateTime;
+import lombok.Data;
 
 /** DTO representing a user notification. */
 @Data
 public class NotificationDto {
+
   private Long id;
   private NotificationType type;
   private PostSummaryDto post;

backend/src/main/java/com/openisle/dto/NotificationMarkReadRequest.java

@@ -1,11 +1,11 @@
 package com.openisle.dto;
 
-import lombok.Data;
-
 import java.util.List;
+import lombok.Data;
 
 /** Request to mark notifications as read. */
 @Data
 public class NotificationMarkReadRequest {
+
   private List<Long> ids;
 }

backend/src/main/java/com/openisle/dto/NotificationPreferenceDto.java

@@ -6,6 +6,7 @@ import lombok.Data;
 /** User notification preference DTO. */
 @Data
 public class NotificationPreferenceDto {
+
   private NotificationType type;
   private boolean enabled;
 }

backend/src/main/java/com/openisle/dto/NotificationPreferenceUpdateRequest.java

@@ -6,6 +6,7 @@ import lombok.Data;
 /** Request to update a single notification preference. */
 @Data
 public class NotificationPreferenceUpdateRequest {
+
   private NotificationType type;
   private boolean enabled;
 }

backend/src/main/java/com/openisle/dto/NotificationUnreadCountDto.java

@@ -5,5 +5,6 @@ import lombok.Data;
 /** DTO representing unread notification count. */
 @Data
 public class NotificationUnreadCountDto {
+
   private long count;
 }

backend/src/main/java/com/openisle/dto/ParentCommentDto.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** DTO representing a parent comment. */
 @Data
 public class ParentCommentDto {
+
   private Long id;
   private String author;
   private String content;

backend/src/main/java/com/openisle/dto/PioneerMedalDto.java

@@ -6,5 +6,6 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class PioneerMedalDto extends MedalDto {
+
   private long rank;
 }

backend/src/main/java/com/openisle/dto/PointGoodDto.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Point mall good info. */
 @Data
 public class PointGoodDto {
+
   private Long id;
   private String name;
   private int cost;

backend/src/main/java/com/openisle/dto/PointHistoryDto.java

@@ -1,14 +1,14 @@
 package com.openisle.dto;
 
 import com.openisle.model.PointHistoryType;
+import java.time.LocalDateTime;
 import lombok.Getter;
 import lombok.Setter;
 
-import java.time.LocalDateTime;
-
 @Getter
 @Setter
 public class PointHistoryDto {
+
   private Long id;
   private PointHistoryType type;
   private int amount;

backend/src/main/java/com/openisle/dto/PointRedeemRequest.java

@@ -5,6 +5,7 @@ import lombok.Data;
 /** Request to redeem a point mall good. */
 @Data
 public class PointRedeemRequest {
+
   private Long goodId;
   private String contact;
 }

backend/src/main/java/com/openisle/dto/PollDto.java

@@ -1,13 +1,13 @@
 package com.openisle.dto;
 
-import lombok.Data;
-
 import java.time.LocalDateTime;
 import java.util.List;
 import java.util.Map;
+import lombok.Data;
 
 @Data
 public class PollDto {
+
   private List<String> options;
   private Map<Integer, Integer> votes;
   private LocalDateTime endTime;

backend/src/main/java/com/openisle/dto/PostChangeLogDto.java

@@ -1,15 +1,15 @@
 package com.openisle.dto;
 
 import com.openisle.model.PostChangeType;
-import lombok.Getter;
-import lombok.Setter;
-
 import java.time.LocalDateTime;
 import java.util.List;
+import lombok.Getter;
+import lombok.Setter;
 
 @Getter
 @Setter
 public class PostChangeLogDto {
+
   private Long id;
   private String username;
   private String userAvatar;

backend/src/main/java/com/openisle/dto/PostDetailDto.java

@@ -1,16 +1,15 @@
 package com.openisle.dto;
 
+import java.util.List;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
-import java.util.List;
-
 /**
  * Detailed DTO for a post, including comments.
  */
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class PostDetailDto extends PostSummaryDto {
+
   private List<CommentDto> comments;
 }
-