文档生成

pkg/openapi/generator.go

@@ -17,6 +17,17 @@ type Generator struct {
 	Reflector *openapi3.Reflector
 }
 
+// SecuritySchemeAgentOpenAPI 表示代理开放接口 Header 签名认证方案
+const SecuritySchemeAgentOpenAPI = "agent_open_api"
+
+const (
+	agentOpenAPIAccountSecurityName   = "AgentOpenAPIAccount"
+	agentOpenAPIPasswordSecurityName  = "AgentOpenAPIPassword"
+	agentOpenAPITimestampSecurityName = "AgentOpenAPITimestamp"
+	agentOpenAPINonceSecurityName     = "AgentOpenAPINonce"
+	agentOpenAPISignSecurityName      = "AgentOpenAPISign"
+)
+
 // NewGenerator 创建一个新的生成器实例
 func NewGenerator(title, version string) *Generator {
 	reflector := openapi3.Reflector{}
@@ -30,6 +41,7 @@ func NewGenerator(title, version string) *Generator {
 
 	g := &Generator{Reflector: &reflector}
 	g.addBearerAuth()
+	g.addAgentOpenAPIAuth()
 	return g
 }
 
@@ -50,6 +62,31 @@ func (g *Generator) addBearerAuth() {
 	g.addErrorResponseSchema()
 }
 
+// addAgentOpenAPIAuth 添加代理开放接口 Header 签名认证定义
+func (g *Generator) addAgentOpenAPIAuth() {
+	g.addAPIKeyHeaderAuth(agentOpenAPIAccountSecurityName, "X-Agent-Account", "代理账号用户名或手机号")
+	g.addAPIKeyHeaderAuth(agentOpenAPIPasswordSecurityName, "X-Agent-Password", "代理账号登录密码")
+	g.addAPIKeyHeaderAuth(agentOpenAPITimestampSecurityName, "X-Agent-Timestamp", "Unix 秒、Unix 毫秒或 RFC3339 时间")
+	g.addAPIKeyHeaderAuth(agentOpenAPINonceSecurityName, "X-Agent-Nonce", "随机串，同一账号在 5 分钟内不可重复")
+	g.addAPIKeyHeaderAuth(agentOpenAPISignSecurityName, "X-Agent-Sign", "请求签名")
+}
+
+// addAPIKeyHeaderAuth 添加一个 Header 类型的 API Key 认证定义
+func (g *Generator) addAPIKeyHeaderAuth(name, header, description string) {
+	g.Reflector.Spec.ComponentsEns().SecuritySchemesEns().WithMapOfSecuritySchemeOrRefValuesItem(
+		name,
+		openapi3.SecuritySchemeOrRef{
+			SecurityScheme: &openapi3.SecurityScheme{
+				APIKeySecurityScheme: &openapi3.APIKeySecurityScheme{
+					Name:        header,
+					In:          openapi3.APIKeySecuritySchemeInHeader,
+					Description: &description,
+				},
+			},
+		},
+	)
+}
+
 // addErrorResponseSchema 添加错误响应 Schema 定义
 func (g *Generator) addErrorResponseSchema() {
 	objectType := openapi3.SchemaType("object")
@@ -121,6 +158,11 @@ type FileUploadField struct {
 //   - tags: 标签列表
 //   - requiresAuth: 是否需要认证
 func (g *Generator) AddOperation(method, path, summary, description string, input interface{}, body interface{}, output interface{}, requiresAuth bool, tags ...string) {
+	g.AddOperationWithSecurity(method, path, summary, description, input, body, output, requiresAuth, "", tags...)
+}
+
+// AddOperationWithSecurity 添加操作并支持指定 OpenAPI 认证方案
+func (g *Generator) AddOperationWithSecurity(method, path, summary, description string, input interface{}, body interface{}, output interface{}, requiresAuth bool, securityScheme string, tags ...string) {
 	op := openapi3.Operation{
 		Summary: &summary,
 		Tags:    tags,
@@ -138,7 +180,7 @@ func (g *Generator) AddOperation(method, path, summary, description string, inpu
 		}
 	}
 
-	// u663eu5f0fu4f20u5165u7684 JSON bodyuff0cu7528u4e8e DELETE u7b49u65b9u6cd5u4e0du81eau52a8u751fu6210 requestBody u7684u573au666f
+	// 显式传入的 JSON body，用于 DELETE 等方法不自动生成 requestBody 的场景
 	if body != nil {
 		tempOp := openapi3.Operation{}
 		if err := g.Reflector.SetRequest(&tempOp, body, "POST"); err != nil {
@@ -157,7 +199,7 @@ func (g *Generator) AddOperation(method, path, summary, description string, inpu
 
 	// 添加认证要求
 	if requiresAuth {
-		g.addSecurityRequirement(&op)
+		g.addSecurityRequirement(&op, securityScheme)
 	}
 
 	// 添加标准错误响应
@@ -251,7 +293,7 @@ func (g *Generator) AddMultipartOperation(method, path, summary, description str
 	}
 
 	if requiresAuth {
-		g.addSecurityRequirement(&op)
+		g.addSecurityRequirement(&op, "")
 	}
 
 	g.addStandardErrorResponses(&op, requiresAuth)
@@ -398,7 +440,20 @@ func (g *Generator) setEnvelopeResponse(op *openapi3.Operation, output interface
 }
 
 // addSecurityRequirement 为操作添加认证要求
-func (g *Generator) addSecurityRequirement(op *openapi3.Operation) {
+func (g *Generator) addSecurityRequirement(op *openapi3.Operation, securityScheme string) {
+	if securityScheme == SecuritySchemeAgentOpenAPI {
+		op.Security = []map[string][]string{
+			{
+				agentOpenAPIAccountSecurityName:   {},
+				agentOpenAPIPasswordSecurityName:  {},
+				agentOpenAPITimestampSecurityName: {},
+				agentOpenAPINonceSecurityName:     {},
+				agentOpenAPISignSecurityName:      {},
+			},
+		}
+		return
+	}
+
 	op.Security = []map[string][]string{
 		{"BearerAuth": {}},
 	}