feat: add securitydefinitions.bearerauth for bearer token setting (#1854

)
swaggo · Oct 17, 2024 · 5a199fc · 5a199fc
1 parent 687052e
commit 5a199fc
Show file tree

Hide file tree

Showing 6 changed files with 69 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -17,34 +17,51 @@
 Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular [Go web frameworks](#supported-web-frameworks). This allows you to quickly integrate with an existing Go project (using Swagger UI).
 
 ## Contents
- - [Getting started](#getting-started)
- - [Supported Web Frameworks](#supported-web-frameworks)
- - [How to use it with Gin](#how-to-use-it-with-gin)
- - [The swag formatter](#the-swag-formatter)
- - [Implementation Status](#implementation-status)
- - [Declarative Comments Format](#declarative-comments-format)
-	- [General API Info](#general-api-info)
-	- [API Operation](#api-operation)
-	- [Security](#security)
- - [Examples](#examples)
-	- [Descriptions over multiple lines](#descriptions-over-multiple-lines)
-	- [User defined structure with an array type](#user-defined-structure-with-an-array-type)
-	- [Function scoped struct declaration](#function-scoped-struct-declaration)
-	- [Model composition in response](#model-composition-in-response)
-	- [Add a headers in response](#add-a-headers-in-response)
-	- [Use multiple path params](#use-multiple-path-params)
-	- [Example value of struct](#example-value-of-struct)
-	- [SchemaExample of body](#schemaexample-of-body)
-	- [Description of struct](#description-of-struct)
-	- [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
-	- [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
-	- [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
-	- [Add extension info to struct field](#add-extension-info-to-struct-field)
-	- [Rename model to display](#rename-model-to-display)
-	- [How to use security annotations](#how-to-use-security-annotations)
-	- [Add a description for enum items](#add-a-description-for-enum-items)
-	- [Generate only specific docs file types](#generate-only-specific-docs-file-types)
-- [About the Project](#about-the-project)
+- [swag](#swag)
+  - [Contents](#contents)
+  - [Getting started](#getting-started)
+  - [swag cli](#swag-cli)
+  - [Supported Web Frameworks](#supported-web-frameworks)
+  - [How to use it with Gin](#how-to-use-it-with-gin)
+  - [The swag formatter](#the-swag-formatter)
+  - [Implementation Status](#implementation-status)
+- [Declarative Comments Format](#declarative-comments-format)
+  - [General API Info](#general-api-info)
+    - [Using markdown descriptions](#using-markdown-descriptions)
+  - [Open API V3.1.0+](#open-api-v310)
+  - [API Operation](#api-operation)
+  - [Mime Types](#mime-types)
+  - [Param Type](#param-type)
+  - [Data Type](#data-type)
+  - [Security](#security)
+  - [Attribute](#attribute)
+    - [Available](#available)
+    - [Future](#future)
+  - [Examples](#examples)
+    - [Descriptions over multiple lines](#descriptions-over-multiple-lines)
+    - [User defined structure with an array type](#user-defined-structure-with-an-array-type)
+    - [Function scoped struct declaration](#function-scoped-struct-declaration)
+    - [Model composition in response](#model-composition-in-response)
+    - [Add a headers in response](#add-a-headers-in-response)
+    - [Use multiple path params](#use-multiple-path-params)
+    - [Add multiple paths](#add-multiple-paths)
+    - [Example value of struct](#example-value-of-struct)
+    - [SchemaExample of body](#schemaexample-of-body)
+    - [Description of struct](#description-of-struct)
+    - [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
+    - [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
+    - [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
+    - [Add extension info to struct field](#add-extension-info-to-struct-field)
+    - [Rename model to display](#rename-model-to-display)
+    - [How to use security annotations](#how-to-use-security-annotations)
+    - [Add a description for enum items](#add-a-description-for-enum-items)
+    - [Generate only specific docs file types](#generate-only-specific-docs-file-types)
+    - [Change the default Go Template action delimiters](#change-the-default-go-template-action-delimiters)
+  - [About the Project](#about-the-project)
+  - [Contributors](#contributors)
+  - [Backers](#backers)
+  - [Sponsors](#sponsors)
+  - [License](#license)
 
 ## Getting started
 
@@ -486,12 +503,13 @@ Besides that, `swag` also accepts aliases for some MIME Types as follows:
 ## Security
 | annotation | description | parameters | example |
 |------------|-------------|------------|---------|
-| securitydefinitions.basic  | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth.  |                                   | // @securityDefinitions.basic BasicAuth                      |
-| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth.            | in, name, description                          | // @securityDefinitions.apikey ApiKeyAuth                    |
-| securitydefinitions.oauth2.application  | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.application OAuth2Application |
-| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | authorizationUrl, scope, description           | // @securitydefinitions.oauth2.implicit OAuth2Implicit       |
-| securitydefinitions.oauth2.password     | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.password OAuth2Password       |
-| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |
+| securitydefinitions.basic               | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth.             |                                                | // @securityDefinitions.basic BasicAuth                      |
+| securitydefinitions.apikey              | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth.                       | in, name, description                          | // @securityDefinitions.apikey ApiKeyAuth                    |
+| securitydefinitions.oauth2.application  | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth.                  | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.application OAuth2Application |
+| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth.                     | authorizationUrl, scope, description           | // @securitydefinitions.oauth2.implicit OAuth2Implicit       |
+| securitydefinitions.oauth2.password     | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth.                     | tokenUrl, scope, description                   | // @securitydefinitions.oauth2.password OAuth2Password       |
+| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth.                  | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |
+| securitydefinitions.bearerauth          | [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) auth. supported in Swagger v3.x|                                                | // @securitydefinitions.bearerauth BearerAuth                |
 
 
 | parameters annotation           | example                                                                 |

diff --git a/parser.go b/parser.go
@@ -59,6 +59,7 @@ const (
 	descriptionMarkdownAttr  = "@description.markdown"
 	secBasicAttr             = "@securitydefinitions.basic"
 	secAPIKeyAttr            = "@securitydefinitions.apikey"
+	secBearerAuthAttr        = "@securitydefinitions.bearerauth"
 	secApplicationAttr       = "@securitydefinitions.oauth2.application"
 	secImplicitAttr          = "@securitydefinitions.oauth2.implicit"
 	secPasswordAttr          = "@securitydefinitions.oauth2.password"

diff --git a/parserv3.go b/parserv3.go
@@ -128,7 +128,7 @@ func (p *Parser) parseGeneralAPIInfoV3(comments []string) error {
 			}
 
 			tag.Spec.ExternalDocs.Spec.Description = value
-		case secBasicAttr, secAPIKeyAttr, secApplicationAttr, secImplicitAttr, secPasswordAttr, secAccessCodeAttr:
+		case secBasicAttr, secAPIKeyAttr, secApplicationAttr, secImplicitAttr, secPasswordAttr, secAccessCodeAttr, secBearerAuthAttr:
 			key, scheme, err := parseSecAttributesV3(attribute, comments, &line)
 			if err != nil {
 				return err
@@ -351,6 +351,13 @@ func parseSecAttributesV3(context string, lines []string, index *int) (string, *
 		search = []string{authorizationURL, in}
 	case secAccessCodeAttr:
 		search = []string{tokenURL, authorizationURL, in}
+	case secBearerAuthAttr:
+		scheme := spec.SecurityScheme{
+			Type:         "http",
+			Scheme:       "bearer",
+			BearerFormat: "JWT",
+		}
+		return "bearerauth", &scheme, nil
 	}
 
 	// For the first line we get the attributes in the context parameter, so we skip to the next one

diff --git a/parserv3_test.go b/parserv3_test.go
@@ -136,7 +136,7 @@ func TestParserParseGeneralApiInfoV3(t *testing.T) {
 	assert.Equal(t, "OpenAPI", p.openAPI.ExternalDocs.Spec.Description)
 	assert.Equal(t, "https://swagger.io/resources/open-api", p.openAPI.ExternalDocs.Spec.URL)
 
-	assert.Equal(t, 6, len(p.openAPI.Components.Spec.SecuritySchemes))
+	assert.Equal(t, 7, len(p.openAPI.Components.Spec.SecuritySchemes))
 
 	security := p.openAPI.Components.Spec.SecuritySchemes
 	assert.Equal(t, "basic", security["basic"].Spec.Spec.Scheme)
@@ -164,6 +164,10 @@ func TestParserParseGeneralApiInfoV3(t *testing.T) {
 	assert.Equal(t, "oauth2", security["OAuth2AccessCode"].Spec.Spec.Type)
 	assert.Equal(t, "header", security["OAuth2AccessCode"].Spec.Spec.In)
 	assert.Equal(t, "https://example.com/oauth/token", security["OAuth2AccessCode"].Spec.Spec.Flows.Spec.AuthorizationCode.Spec.TokenURL)
+
+	assert.Equal(t, "bearer", security["bearerauth"].Spec.Spec.Scheme)
+	assert.Equal(t, "http", security["bearerauth"].Spec.Spec.Type)
+	assert.Equal(t, "JWT", security["bearerauth"].Spec.Spec.BearerFormat)
 }
 
 func TestParser_ParseGeneralApiInfoExtensionsV3(t *testing.T) {

diff --git a/schema.go b/schema.go
@@ -3,6 +3,7 @@ package swag
 import (
 	"errors"
 	"fmt"
+
 	"github.com/go-openapi/spec"
 )
 

diff --git a/testdata/v3/main.go b/testdata/v3/main.go
@@ -54,6 +54,8 @@ package main
 // @in header
 // @name name
 
+// @securitydefinitions.bearerauth BearerAuth
+
 // @externalDocs.description OpenAPI
 // @externalDocs.url https://swagger.io/resources/open-api
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,7 @@ package swag @@
     import (
     	"errors"
     	"fmt"
     	"github.com/go-openapi/spec"
     )
@@ Expand Down @@