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>