From bf754d058c86e92109c80e7f7638009b4c9249d8 Mon Sep 17 00:00:00 2001
From: mediabot-pt <295750538+mediabot-pt@users.noreply.github.com>
Date: Mon, 29 Jun 2026 14:52:43 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E9=9B=86=E6=88=90=20SpringDoc=20OpenAP?=
 =?UTF-8?q?I=20+=20Swagger=20UI=20=E6=96=87=E6=A1=A3=E9=A1=B5=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加 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                               |  6 ++
 .../com/par/api/config/OpenApiConfig.java     | 55 +++++++++++++++++++
 pom.xml                                       |  8 +++
 3 files changed, 69 insertions(+)
 create mode 100644 par-api/src/main/java/com/par/api/config/OpenApiConfig.java

diff --git a/par-api/pom.xml b/par-api/pom.xml
index 1e6f2b2..806c239 100644
--- a/par-api/pom.xml
+++ b/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>
diff --git a/par-api/src/main/java/com/par/api/config/OpenApiConfig.java b/par-api/src/main/java/com/par/api/config/OpenApiConfig.java
new file mode 100644
index 0000000..a30c3fc
--- /dev/null
+++ b/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 头")));
+    }
+}
diff --git a/pom.xml b/pom.xml
index 38778d7..5a1206a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -31,6 +31,7 @@
         <commons-codec.version>1.17.0</commons-codec.version>
         <hutool.version>5.8.27</hutool.version>
         <flyway.version>10.15.0</flyway.version>
+        <springdoc.version>2.5.0</springdoc.version>
     </properties>
 
     <dependencyManagement>
@@ -109,6 +110,13 @@
                 <artifactId>flyway-mysql</artifactId>
                 <version>${flyway.version}</version>
             </dependency>
+
+            <!-- SpringDoc OpenAPI -->
+            <dependency>
+                <groupId>org.springdoc</groupId>
+                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                <version>${springdoc.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>