feat: v2 top level security field (#2030)

Author: 0daryo

README.md

@@ -429,6 +429,7 @@ func (c *Controller) ListAccounts(ctx *gin.Context) {
 | schemes     | The transfer protocol for the operation that separated by spaces. | // @schemes http https |
 | externalDocs.description | Description of the external document. | // @externalDocs.description OpenAPI |
 | externalDocs.url         | URL of the external document. | // @externalDocs.url https://swagger.io/resources/open-api/ |
+| security    | Global security requirements that apply to all operations by default. | // @security ApiKeyAuth |
 | x-name      | The extension key, must be start by x- and take only json value | // @x-example-key {"key": "value"} |
 
 ### Using markdown descriptions
@@ -920,8 +921,13 @@ General API info.
 // @tokenUrl https://example.com/oauth/token
 // @scope.write Grants write access
 // @scope.admin Grants read and write access to administrative information
+
+// @security BasicAuth
+// @security OAuth2Application
 ```
 
+To set global security requirements that apply to all operations by default, use the `@security` annotation in your general API info. This creates a top-level `security` array in the generated OpenAPI specification.
+
 Each API operation.
 
 ```go

field_parser_v3_test.go

@@ -184,7 +184,8 @@ func TestDefaultFieldParserV3(t *testing.T) {
 		t.Parallel()
 
 		schema := spec.NewSchemaSpec()
-		schema.Spec.Type = []string{"string"}
+		typeArray := spec.NewSingleOrArray("string")
+		schema.Spec.Type = &typeArray
 		parser := &Parser{}
 		fieldParser := newTagBaseFieldParserV3(
 			parser,

parserv3.go

@@ -142,6 +142,9 @@ func (p *Parser) parseGeneralAPIInfoV3(comments []string) error {
 
 			p.openAPI.Components.Spec.SecuritySchemes[key] = schemeSpec
 
+		case securityAttr:
+			p.openAPI.Security = append(p.openAPI.Security, parseSecurity(value))
+
 		case "@query.collection.format":
 			p.collectionFormatInQuery = TransToValidCollectionFormat(value)
 

parserv3_test.go

@@ -497,6 +497,53 @@ func TestParserParseServers(t *testing.T) {
 
 }
 
+func TestParserParseGeneralAPIInfoGlobalSecurityV3(t *testing.T) {
+	t.Parallel()
+
+	// Test simple global security
+	parser := New(GenerateOpenAPI3Doc(true))
+	err := parser.parseGeneralAPIInfoV3([]string{
+		"@security ApiKeyAuth",
+	})
+	assert.NoError(t, err)
+	assert.Len(t, parser.openAPI.Security, 1)
+	assert.Contains(t, parser.openAPI.Security[0], "ApiKeyAuth")
+	assert.Equal(t, []string{}, parser.openAPI.Security[0]["ApiKeyAuth"])
+
+	// Test OAuth2 with scopes
+	parser2 := New(GenerateOpenAPI3Doc(true))
+	err2 := parser2.parseGeneralAPIInfoV3([]string{
+		"@security OAuth2Implicit[read,write]",
+	})
+	assert.NoError(t, err2)
+	assert.Len(t, parser2.openAPI.Security, 1)
+	assert.Contains(t, parser2.openAPI.Security[0], "OAuth2Implicit")
+	assert.Equal(t, []string{"read", "write"}, parser2.openAPI.Security[0]["OAuth2Implicit"])
+
+	// Test OR logic
+	parser3 := New(GenerateOpenAPI3Doc(true))
+	err3 := parser3.parseGeneralAPIInfoV3([]string{
+		"@security ApiKeyAuth || BasicAuth",
+	})
+	assert.NoError(t, err3)
+	assert.Len(t, parser3.openAPI.Security, 1)
+	assert.Contains(t, parser3.openAPI.Security[0], "ApiKeyAuth")
+	assert.Contains(t, parser3.openAPI.Security[0], "BasicAuth")
+	assert.Equal(t, []string{}, parser3.openAPI.Security[0]["ApiKeyAuth"])
+	assert.Equal(t, []string{}, parser3.openAPI.Security[0]["BasicAuth"])
+
+	// Test AND logic (multiple @security lines)
+	parser4 := New(GenerateOpenAPI3Doc(true))
+	err4 := parser4.parseGeneralAPIInfoV3([]string{
+		"@security ApiKeyAuth",
+		"@security BasicAuth",
+	})
+	assert.NoError(t, err4)
+	assert.Len(t, parser4.openAPI.Security, 2)
+	assert.Contains(t, parser4.openAPI.Security[0], "ApiKeyAuth")
+	assert.Contains(t, parser4.openAPI.Security[1], "BasicAuth")
+}
+
 func TestParseTypeAlias(t *testing.T) {
 	t.Parallel()