feat: 集成 SpringDoc OpenAPI + Swagger UI 文档页面

- 添加 springdoc-openapi-starter-webmvc-ui 2.5.0
- OpenApiConfig 配置 API 标题、描述、版本、认证方案
- 文档包含 Bearer Token 和 HMAC 签名两种认证说明
- Swagger UI: /swagger-ui.html
- OpenAPI JSON: /v3/api-docs

par-api/pom.xml

@@ -47,6 +47,12 @@
             <artifactId>lombok</artifactId>
             <optional>true</optional>
         </dependency>
+
+        <!-- SpringDoc OpenAPI / Swagger UI -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+        </dependency>
     </dependencies>
 
     <build>

par-api/src/main/java/com/par/api/config/OpenApiConfig.java

@@ -0,0 +1,55 @@
+package com.par.api.config;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * OpenAPI / Swagger 配置
+ */
+@Configuration
+public class OpenApiConfig {
+
+    @Bean
+    public OpenAPI parOpenAPI() {
+        return new OpenAPI()
+                .info(new Info()
+                        .title("PAR Server API")
+                        .description("PT Adapter Registry — 适配器配置注册中心\n\n"
+                                + "## 认证方式\n"
+                                + "- **Bearer Token**: 管理后台登录后获取，24h 有效，用于 `/api/v1/admin/**` 接口\n"
+                                + "- **HMAC 签名**: 外部工具集成使用，以 `X-Signature` / `X-Timestamp` / `X-Email` 头携带\n\n"
+                                + "## 端点分类\n"
+                                + "- **公开读取**: `/health`, `/api/v1/sites/**`, `/api/v1/configs/**`, `/api/v1/manifest`\n"
+                                + "- **需认证**: `/api/v1/auth/**` (登录/注册)\n"
+                                + "- **HMAC 签名**: `/api/v1/configs/*/submit`, `/api/v1/sites/*/submit`\n"
+                                + "- **管理员**: `/api/v1/admin/**` (Bearer Token)\n"
+                                + "- **账户**: `/api/v1/account/**` (Bearer Token)")
+                        .version("v1.0.0")
+                        .contact(new Contact()
+                                .name("PAR Team")
+                                .email("admin@par.local"))
+                        .license(new License()
+                                .name("MIT")
+                                .url("https://opensource.org/licenses/MIT")))
+                .addSecurityItem(new SecurityRequirement().addList("Bearer"))
+                .addSecurityItem(new SecurityRequirement().addList("HMAC"))
+                .components(new Components()
+                        .addSecuritySchemes("Bearer", new SecurityScheme()
+                                .type(SecurityScheme.Type.HTTP)
+                                .scheme("bearer")
+                                .bearerFormat("custom")
+                                .description("登录接口返回的 token"))
+                        .addSecuritySchemes("HMAC", new SecurityScheme()
+                                .type(SecurityScheme.Type.APIKEY)
+                                .in(SecurityScheme.In.HEADER)
+                                .name("X-Signature")
+                                .description("HMAC-SHA256 签名，需同时携带 X-Timestamp 和 X-Email 头")));
+    }
+}