feat(openapi): 添加 Operation.SecurityScheme

openapi/middleware.go

@@ -365,6 +365,26 @@ func (o *Operation) Callback(name, path, method string, f func(*Operation)) *Ope
 	return o
 }
 
+// SecuritySecheme 根据此 s 生成适用于当前接口的认证方式
+//
+// 如果 s.ID 不存在于 [Document.Components.securitySchemes] 将自动添加；
+func (o *Operation) SecuritySecheme(s *SecurityScheme, scope ...string) *Operation {
+	if _, found := o.d.components.securitySchemes[s.ID]; !found {
+		if err := s.valid(); err != nil {
+			panic(err)
+		}
+
+		o.d.components.securitySchemes[s.ID] = s
+	}
+
+	if o.Security == nil {
+		o.Security = []*SecurityRequirement{}
+	}
+	o.Security = append(o.Security, &SecurityRequirement{Name: s.ID, Scopes: scope})
+
+	return o
+}
+
 // API 提供用于声明 openapi 文档的中间件
 //
 // 用户可通过 f 方法提供的参数 o 对接口数据进行更改。

openapi/option.go

@@ -331,6 +331,7 @@ func (d *Document) WithTag(name string, desc web.LocaleStringer, extDocURL strin
 //
 // s 需要添加的验证方案；
 // scope 如果指定了该值，那么会以 s.ID 为名称，scope 为值添加至 openapi.security，
+// 如果仅需要添加至 components 中，则需要将 scope 指定为 Nil。
 // scope 如果是多个参数，每个参数应该都是不同的；
 //
 // NOTE: 多次调用会依次添加