feat: OpenAPI Spec support #123

Author: soulteary

README-zhCN.md

@@ -13,7 +13,7 @@
 - ⚡ **高性能**：可配置并发、速率限制（含基于 Redis 的分布式限流）与优化的请求处理
 - 🎯 **灵活配置**：支持 JSON 和 YAML 配置文件，支持 Go 模板
 - 🔐 **高级认证**：多种触发规则类型，包括 HMAC 签名验证、IP 白名单和自定义规则
-- 📊 **可观测性**：内置 Prometheus 指标、健康检查端点、OpenTelemetry 追踪、审计日志与全面日志
+- 📊 **可观测性**：内置 Prometheus 指标、健康检查端点、可选 OpenAPI 规范（便于 Swagger/客户端生成）、OpenTelemetry 追踪、审计日志与全面日志
 - 🐳 **容器就绪**：官方 Docker 镜像，提供多个变体
 - 🌍 **国际化**：完整的中英文文档支持
 - 🔄 **热重载**：无需重启服务器即可更新钩子配置

README.md

@@ -13,7 +13,7 @@
 - ⚡ **High Performance**: Configurable concurrency, rate limiting (including Redis-backed distributed), and optimized request handling
 - 🎯 **Flexible Configuration**: Support for JSON and YAML configuration files with Go template support
 - 🔐 **Advanced Authentication**: Multiple trigger rule types including HMAC signature validation, IP whitelisting, and custom rules
-- 📊 **Observability**: Built-in Prometheus metrics, health check endpoint, OpenTelemetry tracing, audit logging, and comprehensive logging
+- 📊 **Observability**: Built-in Prometheus metrics, health check endpoint, optional OpenAPI spec (for Swagger/client generation), OpenTelemetry tracing, audit logging, and comprehensive logging
 - 🐳 **Container Ready**: Official Docker images with multiple variants
 - 🌍 **Internationalization**: Full support for English and Chinese documentation
 - 🔄 **Hot Reload**: Update hook configurations without restarting the server

cmd/config-ui/main.go

@@ -34,41 +34,41 @@ const (
 )
 
 type pageData struct {
-	I18N            template.JS
-	Title           string
-	Lang            string
-	ConfigSections  []configSection
+	I18N           template.JS
+	Title          string
+	Lang           string
+	ConfigSections []configSection
 }
 
 type configSection struct {
-	TitleKey   string         `yaml:"titleKey"`
-	Options    []configOption `yaml:"options"`
-	Collapsible bool         `yaml:"collapsible"`
+	TitleKey    string         `yaml:"titleKey"`
+	Options     []configOption `yaml:"options"`
+	Collapsible bool           `yaml:"collapsible"`
 }
 
 type configOption struct {
-	Type       string `yaml:"type"`
-	ID         string `yaml:"id"`
-	Name       string `yaml:"name"`
-	LabelKey   string `yaml:"labelKey"`
-	DescKey    string `yaml:"descKey"`
+	Type        string `yaml:"type"`
+	ID          string `yaml:"id"`
+	Name        string `yaml:"name"`
+	LabelKey    string `yaml:"labelKey"`
+	DescKey     string `yaml:"descKey"`
 	Placeholder string `yaml:"placeholder"`
-	Default    string `yaml:"default"`
+	Default     string `yaml:"default"`
 }
 
 type pageYAML struct {
 	I18N           map[string]map[string]string `yaml:"i18n"`
-	ConfigSections []configSection             `yaml:"configSections"`
+	ConfigSections []configSection              `yaml:"configSections"`
 }
 
 type generateRequest struct {
-	ID                              string `json:"id"`
-	ExecuteCommand                  string `json:"execute-command"`
+	ID                             string `json:"id"`
+	ExecuteCommand                 string `json:"execute-command"`
 	CommandWorkingDirectory        string `json:"command-working-directory"`
 	ResponseMessage                string `json:"response-message"`
 	HTTPMethods                    string `json:"http-methods"` // comma-separated or single
 	SuccessHTTPResponseCode        int    `json:"success-http-response-code"`
-	IncludeCommandOutputInResponse  bool   `json:"include-command-output-in-response"`
+	IncludeCommandOutputInResponse bool   `json:"include-command-output-in-response"`
 	WebhookBaseURL                 string `json:"webhook_base_url"` // e.g. http://localhost:9000
 	ResponseHeadersJSON            string `json:"response-headers"`
 	PassArgumentsToCommandJSON     string `json:"pass-arguments-to-command"`
@@ -181,14 +181,14 @@ func requestToHook(req *generateRequest) *hook.Hook {
 		return nil
 	}
 	h := &hook.Hook{
-		ID:                          strings.TrimSpace(req.ID),
-		ExecuteCommand:              strings.TrimSpace(req.ExecuteCommand),
-		CommandWorkingDirectory:     strings.TrimSpace(req.CommandWorkingDirectory),
-		ResponseMessage:             strings.TrimSpace(req.ResponseMessage),
-		HTTPMethods:                 parseHTTPMethods(req.HTTPMethods),
-		SuccessHttpResponseCode:     successCode(req.SuccessHTTPResponseCode),
-		CaptureCommandOutput:        req.IncludeCommandOutputInResponse,
-		IncomingPayloadContentType:  strings.TrimSpace(req.IncomingPayloadContentType),
+		ID:                         strings.TrimSpace(req.ID),
+		ExecuteCommand:             strings.TrimSpace(req.ExecuteCommand),
+		CommandWorkingDirectory:    strings.TrimSpace(req.CommandWorkingDirectory),
+		ResponseMessage:            strings.TrimSpace(req.ResponseMessage),
+		HTTPMethods:                parseHTTPMethods(req.HTTPMethods),
+		SuccessHttpResponseCode:    successCode(req.SuccessHTTPResponseCode),
+		CaptureCommandOutput:       req.IncludeCommandOutputInResponse,
+		IncomingPayloadContentType: strings.TrimSpace(req.IncomingPayloadContentType),
 	}
 	if req.ResponseHeadersJSON != "" {
 		var headers []hook.Header

cmd/config-ui/main_test.go

@@ -86,10 +86,10 @@ func TestValidateOptionalJSON(t *testing.T) {
 
 func TestRequestToHook(t *testing.T) {
 	req := &generateRequest{
-		ID:                 "test-hook",
-		ExecuteCommand:     "/bin/true",
-		ResponseMessage:    "OK",
-		HTTPMethods:        "POST",
+		ID:                      "test-hook",
+		ExecuteCommand:          "/bin/true",
+		ResponseMessage:         "OK",
+		HTTPMethods:             "POST",
 		SuccessHTTPResponseCode: 200,
 	}
 	h := requestToHook(req)

docs/en-US/API-Reference.md

@@ -81,7 +81,33 @@ curl http://localhost:9000/metrics
 
 ---
 
-### 4. Hook Execution Endpoint
+### 4. OpenAPI Specification Endpoint (Optional)
+
+**Endpoint:** `GET /openapi` (or custom path via `-openapi-path`)
+
+**Availability:** Only when the server is started with the `-openapi` flag (or `OPENAPI_ENABLED=true`). Not exposed by default. Recommend use only for debugging or intranet.
+
+**Description:** Returns the OpenAPI 3.0.x specification (JSON) for the webhook HTTP API. Use with Swagger UI, Swagger Editor, or client code generators.
+
+**Response:**
+- **Status Code:** `200 OK`
+- **Content-Type:** `application/json; charset=utf-8`
+- **Body:** OpenAPI 3.0.3 document describing `/`, `/health`, `/livez`, `/readyz`, `/version`, `/metrics`, and `/hooks/{id}` (or custom hook prefix).
+
+**Example:**
+```bash
+# Start server with OpenAPI enabled
+./webhook -hooks hooks.json -openapi
+
+# Fetch the spec
+curl http://localhost:9000/openapi
+```
+
+You can also print the spec to stdout at startup with `-openapi-print` (e.g. `./webhook -openapi -openapi-print > openapi.json`).
+
+---
+
+### 5. Hook Execution Endpoint
 
 **Endpoint:** `POST|GET|PUT|DELETE /hooks/{hook-id}`
 

docs/en-US/Webhook-Parameters.md

@@ -130,6 +130,16 @@ This document describes all available command-line parameters and environment va
 | `-audit-workers int` | Number of audit async write workers | `2` |
 | `-audit-mask-ip` | Mask IP addresses in audit logs | `true` |
 
+### OpenAPI
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-openapi` | Enable OpenAPI spec: serve at openapi-path and/or print to stdout; recommend only for debugging or intranet | `false` |
+| `-openapi-path string` | HTTP path for OpenAPI spec when openapi is enabled | `/openapi` |
+| `-openapi-print` | Print OpenAPI spec to stdout at startup when openapi is enabled | `false` |
+
+*Note:* When `-openapi` is set, the spec is available via GET at `-openapi-path` (e.g. `/openapi`) and can be used with Swagger UI or client code generation. Use only in debugging or intranet environments. Do not set `-openapi-path` to a reserved path (e.g. `/`, `/health`, `/version`, `/metrics`, or the hooks prefix like `/hooks`); if you do, the OpenAPI route will not be registered and a warning will be logged.
+
 ### Other
 
 | Flag | Description | Default |
@@ -256,6 +266,14 @@ All command-line parameters can also be set via environment variables:
 | `AUDIT_WORKERS` | `-audit-workers` | Audit async workers | `2` |
 | `AUDIT_MASK_IP` | `-audit-mask-ip` | Mask IP in audit logs | `true` |
 
+### OpenAPI
+
+| Environment Variable | CLI Flag | Description | Default |
+|---------------------|----------|-------------|---------|
+| `OPENAPI_ENABLED` | `-openapi` | Enable OpenAPI spec | `false` |
+| `OPENAPI_PATH` | `-openapi-path` | HTTP path for OpenAPI spec | `/openapi` |
+| `OPENAPI_PRINT` | `-openapi-print` | Print OpenAPI spec to stdout at startup | `false` |
+
 ## Security Best Practices
 
 ### Command Path Whitelisting
@@ -322,6 +340,10 @@ Alternatively, use `-hotreload` (or `HOT_RELOAD=true`) for automatic hot reloadi
   -write-timeout-seconds=60 \
   -max-concurrent-hooks=20
 
+# With OpenAPI spec (for Swagger UI or client generation; recommend debugging/intranet only)
+./webhook -hooks hooks.json -openapi
+# Or print spec to stdout: ./webhook -hooks hooks.json -openapi -openapi-print > openapi.json
+
 # Using environment variables
 export PORT=8080
 export HOOKS=/path/to/hooks.json

docs/zh-CN/API-Reference.md

@@ -81,7 +81,33 @@ curl http://localhost:9000/metrics
 
 ---
 
-### 4. Hook 执行端点
+### 4. OpenAPI 规范端点（可选）
+
+**端点:** `GET /openapi`（或通过 `-openapi-path` 自定义路径）
+
+**可用性:** 仅当使用 `-openapi` 参数（或 `OPENAPI_ENABLED=true`）启动服务时可用。默认不暴露，建议仅在调试或内网使用。
+
+**描述:** 返回 Webhook HTTP API 的 OpenAPI 3.0.x 规范（JSON），可用于 Swagger UI、Swagger Editor 或客户端代码生成。
+
+**响应:**
+- **状态码:** `200 OK`
+- **Content-Type:** `application/json; charset=utf-8`
+- **响应体:** 描述 `/`、`/health`、`/livez`、`/readyz`、`/version`、`/metrics` 及 `/hooks/{id}`（或自定义 hook 前缀）的 OpenAPI 3.0.3 文档。
+
+**示例:**
+```bash
+# 启用 OpenAPI 后启动服务
+./webhook -hooks hooks.json -openapi
+
+# 获取规范
+curl http://localhost:9000/openapi
+```
+
+也可使用 `-openapi-print` 在启动时将规范打印到 stdout（例如 `./webhook -openapi -openapi-print > openapi.json`）。
+
+---
+
+### 5. Hook 执行端点
 
 **端点:** `POST|GET|PUT|DELETE /hooks/{hook-id}`
 

docs/zh-CN/CLI-ENV.md

@@ -243,6 +243,21 @@
 - `-audit-mask-ip`
   在审计日志中脱敏 IP 地址（默认值：`true`）
 
+### OpenAPI
+
+以下参数用于可选地暴露 OpenAPI 规范（便于客户端集成或 Swagger 调试）；**建议仅在调试或内网环境使用**。
+
+- `-openapi`
+  启用 OpenAPI 规范：在 openapi-path 提供 GET 和/或启动时打印到 stdout（默认值：`false`）
+
+- `-openapi-path string`
+  启用 openapi 时，提供 OpenAPI 规范的 HTTP 路径（默认值：`/openapi`）
+  
+  请勿设置为与现有端点冲突的路径（如 `/`、`/health`、`/version`、`/metrics` 等）。
+
+- `-openapi-print`
+  启用 openapi 时，在启动时将规范打印到标准输出（默认值：`false`）
+
 ### 其他
 
 - `-version`
@@ -372,6 +387,14 @@
 | `AUDIT_WORKERS` | `-audit-workers` | 异步写入工作协程数 | `2` |
 | `AUDIT_MASK_IP` | `-audit-mask-ip` | 审计日志中脱敏 IP | `true` |
 
+### OpenAPI
+
+| 环境变量 | 命令行参数 | 说明 | 默认值 |
+|---------|-----------|------|--------|
+| `OPENAPI_ENABLED` | `-openapi` | 启用 OpenAPI 规范 | `false` |
+| `OPENAPI_PATH` | `-openapi-path` | OpenAPI 规范 HTTP 路径 | `/openapi` |
+| `OPENAPI_PRINT` | `-openapi-print` | 启动时打印规范到 stdout | `false` |
+
 ### 环境变量使用示例
 
 ```bash
@@ -402,6 +425,10 @@ export ALLOWED_COMMAND_PATHS="/usr/bin,/opt/scripts"
 export MAX_ARG_LENGTH=1048576
 export STRICT_MODE=true
 
+# 可选：启用 OpenAPI 规范（仅建议在调试或内网使用）
+# export OPENAPI_ENABLED=true
+# export OPENAPI_PRINT=true   # 启动时打印到 stdout
+
 # 运行 webhook
 ./webhook
 ```

internal/flags/config.go

@@ -87,6 +87,11 @@ func ParseConfig() AppFlags {
 	fs.Int("audit-workers", DEFAULT_AUDIT_WORKERS, "number of audit async write workers (default 2)")
 	fs.Bool("audit-mask-ip", DEFAULT_AUDIT_MASK_IP, "mask IP addresses in audit logs (default true)")
 
+	// OpenAPI flags (recommend only for debugging or intranet)
+	fs.Bool("openapi", DEFAULT_OPENAPI_ENABLED, "enable OpenAPI spec: serve at openapi-path and/or print to stdout; recommend only for debugging or intranet (default false)")
+	fs.String("openapi-path", DEFAULT_OPENAPI_PATH, "HTTP path for OpenAPI spec when openapi is enabled (default /openapi)")
+	fs.Bool("openapi-print", DEFAULT_OPENAPI_PRINT, "print OpenAPI spec to stdout at startup when openapi is enabled (default false)")
+
 	showVersion := fs.Bool("version", false, "display webhook version and quit")
 	validateConfig := fs.Bool("validate-config", false, "validate configuration and exit")
 
@@ -181,6 +186,11 @@ func ParseConfig() AppFlags {
 	flags.AuditWorkers = configutil.ResolveInt(fs, "audit-workers", ENV_KEY_AUDIT_WORKERS, DEFAULT_AUDIT_WORKERS, false)
 	flags.AuditMaskIP = configutil.ResolveBool(fs, "audit-mask-ip", ENV_KEY_AUDIT_MASK_IP, DEFAULT_AUDIT_MASK_IP)
 
+	// OpenAPI settings
+	flags.OpenAPIEnabled = configutil.ResolveBool(fs, "openapi", ENV_KEY_OPENAPI_ENABLED, DEFAULT_OPENAPI_ENABLED)
+	flags.OpenAPIPath = configutil.ResolveString(fs, "openapi-path", ENV_KEY_OPENAPI_PATH, DEFAULT_OPENAPI_PATH, true)
+	flags.OpenAPIPrint = configutil.ResolveBool(fs, "openapi-print", ENV_KEY_OPENAPI_PRINT, DEFAULT_OPENAPI_PRINT)
+
 	// Special flags
 	flags.ShowVersion = *showVersion
 	flags.ValidateConfig = *validateConfig

internal/flags/define.go

@@ -75,6 +75,11 @@ const (
 	DEFAULT_AUDIT_QUEUE_SIZE   = 1000
 	DEFAULT_AUDIT_WORKERS      = 2
 	DEFAULT_AUDIT_MASK_IP      = true
+
+	// OpenAPI defaults
+	DEFAULT_OPENAPI_ENABLED = false
+	DEFAULT_OPENAPI_PATH    = "/openapi"
+	DEFAULT_OPENAPI_PRINT   = false
 )
 
 const (
@@ -149,6 +154,11 @@ const (
 	ENV_KEY_AUDIT_QUEUE_SIZE   = "AUDIT_QUEUE_SIZE"
 	ENV_KEY_AUDIT_WORKERS      = "AUDIT_WORKERS"
 	ENV_KEY_AUDIT_MASK_IP      = "AUDIT_MASK_IP"
+
+	// OpenAPI environment keys
+	ENV_KEY_OPENAPI_ENABLED = "OPENAPI_ENABLED"
+	ENV_KEY_OPENAPI_PATH    = "OPENAPI_PATH"
+	ENV_KEY_OPENAPI_PRINT   = "OPENAPI_PRINT"
 )
 
 type AppFlags struct {
@@ -225,4 +235,9 @@ type AppFlags struct {
 	AuditQueueSize   int    // 异步写入队列大小
 	AuditWorkers     int    // 异步写入工作协程数
 	AuditMaskIP      bool   // 是否对 IP 地址进行脱敏
+
+	// OpenAPI settings
+	OpenAPIEnabled bool   // 是否启用 OpenAPI 规范（GET 路径或打印）
+	OpenAPIPath    string // OpenAPI 规范 HTTP 路径（默认 /openapi）
+	OpenAPIPrint   bool   // 是否在启动时将规范打印到 stdout
 }