Skip to content

Commit 5a199fc

Browse files
XiXiangFilesXiXiangFiles
authored
feat: add securitydefinitions.bearerauth for bearer token setting (#1854)
1 parent 687052e commit 5a199fc

File tree

6 files changed

+69
-36
lines changed

6 files changed

+69
-36
lines changed

‎README.md‎

Lines changed: 52 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -17,34 +17,51 @@
1717
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).
1818

1919
## Contents
20-
- [Getting started](#getting-started)
21-
- [Supported Web Frameworks](#supported-web-frameworks)
22-
- [How to use it with Gin](#how-to-use-it-with-gin)
23-
- [The swag formatter](#the-swag-formatter)
24-
- [Implementation Status](#implementation-status)
25-
- [Declarative Comments Format](#declarative-comments-format)
26-
- [General API Info](#general-api-info)
27-
- [API Operation](#api-operation)
28-
- [Security](#security)
29-
- [Examples](#examples)
30-
- [Descriptions over multiple lines](#descriptions-over-multiple-lines)
31-
- [User defined structure with an array type](#user-defined-structure-with-an-array-type)
32-
- [Function scoped struct declaration](#function-scoped-struct-declaration)
33-
- [Model composition in response](#model-composition-in-response)
34-
- [Add a headers in response](#add-a-headers-in-response)
35-
- [Use multiple path params](#use-multiple-path-params)
36-
- [Example value of struct](#example-value-of-struct)
37-
- [SchemaExample of body](#schemaexample-of-body)
38-
- [Description of struct](#description-of-struct)
39-
- [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
40-
- [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
41-
- [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
42-
- [Add extension info to struct field](#add-extension-info-to-struct-field)
43-
- [Rename model to display](#rename-model-to-display)
44-
- [How to use security annotations](#how-to-use-security-annotations)
45-
- [Add a description for enum items](#add-a-description-for-enum-items)
46-
- [Generate only specific docs file types](#generate-only-specific-docs-file-types)
47-
- [About the Project](#about-the-project)
20+
- [swag](#swag)
21+
- [Contents](#contents)
22+
- [Getting started](#getting-started)
23+
- [swag cli](#swag-cli)
24+
- [Supported Web Frameworks](#supported-web-frameworks)
25+
- [How to use it with Gin](#how-to-use-it-with-gin)
26+
- [The swag formatter](#the-swag-formatter)
27+
- [Implementation Status](#implementation-status)
28+
- [Declarative Comments Format](#declarative-comments-format)
29+
- [General API Info](#general-api-info)
30+
- [Using markdown descriptions](#using-markdown-descriptions)
31+
- [Open API V3.1.0+](#open-api-v310)
32+
- [API Operation](#api-operation)
33+
- [Mime Types](#mime-types)
34+
- [Param Type](#param-type)
35+
- [Data Type](#data-type)
36+
- [Security](#security)
37+
- [Attribute](#attribute)
38+
- [Available](#available)
39+
- [Future](#future)
40+
- [Examples](#examples)
41+
- [Descriptions over multiple lines](#descriptions-over-multiple-lines)
42+
- [User defined structure with an array type](#user-defined-structure-with-an-array-type)
43+
- [Function scoped struct declaration](#function-scoped-struct-declaration)
44+
- [Model composition in response](#model-composition-in-response)
45+
- [Add a headers in response](#add-a-headers-in-response)
46+
- [Use multiple path params](#use-multiple-path-params)
47+
- [Add multiple paths](#add-multiple-paths)
48+
- [Example value of struct](#example-value-of-struct)
49+
- [SchemaExample of body](#schemaexample-of-body)
50+
- [Description of struct](#description-of-struct)
51+
- [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
52+
- [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
53+
- [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
54+
- [Add extension info to struct field](#add-extension-info-to-struct-field)
55+
- [Rename model to display](#rename-model-to-display)
56+
- [How to use security annotations](#how-to-use-security-annotations)
57+
- [Add a description for enum items](#add-a-description-for-enum-items)
58+
- [Generate only specific docs file types](#generate-only-specific-docs-file-types)
59+
- [Change the default Go Template action delimiters](#change-the-default-go-template-action-delimiters)
60+
- [About the Project](#about-the-project)
61+
- [Contributors](#contributors)
62+
- [Backers](#backers)
63+
- [Sponsors](#sponsors)
64+
- [License](#license)
4865

4966
## Getting started
5067

@@ -486,12 +503,13 @@ Besides that, `swag` also accepts aliases for some MIME Types as follows:
486503
## Security
487504
| annotation | description | parameters | example |
488505
|------------|-------------|------------|---------|
489-
| securitydefinitions.basic | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basic BasicAuth |
490-
| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth |
491-
| securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application |
492-
| securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit |
493-
| securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password |
494-
| securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode |
506+
| securitydefinitions.basic | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basic BasicAuth |
507+
| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth |
508+
| securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application |
509+
| securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit |
510+
| securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password |
511+
| securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode |
512+
| securitydefinitions.bearerauth | [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) auth. supported in Swagger v3.x| | // @securitydefinitions.bearerauth BearerAuth |
495513
496514
497515
| parameters annotation | example |

‎parser.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ const (
5959
descriptionMarkdownAttr = "@description.markdown"
6060
secBasicAttr = "@securitydefinitions.basic"
6161
secAPIKeyAttr = "@securitydefinitions.apikey"
62+
secBearerAuthAttr = "@securitydefinitions.bearerauth"
6263
secApplicationAttr = "@securitydefinitions.oauth2.application"
6364
secImplicitAttr = "@securitydefinitions.oauth2.implicit"
6465
secPasswordAttr = "@securitydefinitions.oauth2.password"

‎parserv3.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ func (p *Parser) parseGeneralAPIInfoV3(comments []string) error {
128128
}
129129

130130
tag.Spec.ExternalDocs.Spec.Description = value
131-
case secBasicAttr, secAPIKeyAttr, secApplicationAttr, secImplicitAttr, secPasswordAttr, secAccessCodeAttr:
131+
case secBasicAttr, secAPIKeyAttr, secApplicationAttr, secImplicitAttr, secPasswordAttr, secAccessCodeAttr, secBearerAuthAttr:
132132
key, scheme, err := parseSecAttributesV3(attribute, comments, &line)
133133
if err != nil {
134134
return err
@@ -351,6 +351,13 @@ func parseSecAttributesV3(context string, lines []string, index *int) (string, *
351351
search = []string{authorizationURL, in}
352352
case secAccessCodeAttr:
353353
search = []string{tokenURL, authorizationURL, in}
354+
case secBearerAuthAttr:
355+
scheme := spec.SecurityScheme{
356+
Type: "http",
357+
Scheme: "bearer",
358+
BearerFormat: "JWT",
359+
}
360+
return "bearerauth", &scheme, nil
354361
}
355362

356363
// For the first line we get the attributes in the context parameter, so we skip to the next one

‎parserv3_test.go‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ func TestParserParseGeneralApiInfoV3(t *testing.T) {
136136
assert.Equal(t, "OpenAPI", p.openAPI.ExternalDocs.Spec.Description)
137137
assert.Equal(t, "https://swagger.io/resources/open-api", p.openAPI.ExternalDocs.Spec.URL)
138138

139-
assert.Equal(t, 6, len(p.openAPI.Components.Spec.SecuritySchemes))
139+
assert.Equal(t, 7, len(p.openAPI.Components.Spec.SecuritySchemes))
140140

141141
security := p.openAPI.Components.Spec.SecuritySchemes
142142
assert.Equal(t, "basic", security["basic"].Spec.Spec.Scheme)
@@ -164,6 +164,10 @@ func TestParserParseGeneralApiInfoV3(t *testing.T) {
164164
assert.Equal(t, "oauth2", security["OAuth2AccessCode"].Spec.Spec.Type)
165165
assert.Equal(t, "header", security["OAuth2AccessCode"].Spec.Spec.In)
166166
assert.Equal(t, "https://example.com/oauth/token", security["OAuth2AccessCode"].Spec.Spec.Flows.Spec.AuthorizationCode.Spec.TokenURL)
167+
168+
assert.Equal(t, "bearer", security["bearerauth"].Spec.Spec.Scheme)
169+
assert.Equal(t, "http", security["bearerauth"].Spec.Spec.Type)
170+
assert.Equal(t, "JWT", security["bearerauth"].Spec.Spec.BearerFormat)
167171
}
168172

169173
func TestParser_ParseGeneralApiInfoExtensionsV3(t *testing.T) {

‎schema.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package swag
33
import (
44
"errors"
55
"fmt"
6+
67
"github.com/go-openapi/spec"
78
)
89

‎testdata/v3/main.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ package main
5454
// @in header
5555
// @name name
5656

57+
// @securitydefinitions.bearerauth BearerAuth
58+
5759
// @externalDocs.description OpenAPI
5860
// @externalDocs.url https://swagger.io/resources/open-api
5961

0 commit comments

Comments
 (0)