added security definition description

README.md

@@ -9,7 +9,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/swaggo/swag)](https://goreportcard.com/report/github.com/swaggo/swag)
 [![codebeat badge](https://codebeat.co/badges/71e2f5e5-9e6b-405d-baf9-7cc8b5037330)](https://codebeat.co/projects/github-com-swaggo-swag-master)
 [![Go Doc](https://godoc.org/github.com/swaggo/swagg?status.svg)](https://godoc.org/github.com/swaggo/swag)
-[![Backers on Open Collective](https://opencollective.com/swag/backers/badge.svg)](#backers) 
+[![Backers on Open Collective](https://opencollective.com/swag/backers/badge.svg)](#backers)
 [![Sponsors on Open Collective](https://opencollective.com/swag/sponsors/badge.svg)](#sponsors) [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fswaggo%2Fswag.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_shield)
 [![Release](https://img.shields.io/github/release/swaggo/swag.svg?style=flat-square)](https://github.com/swaggo/swag/releases)
 
@@ -30,7 +30,7 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie
 	- [Descriptions over multiple lines](#descriptions-over-multiple-lines)
 	- [User defined structure with an array type](#user-defined-structure-with-an-array-type)
 	- [Model composition in response](#model-composition-in-response)
-	- [Add a headers in response](#add-a-headers-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)
@@ -193,7 +193,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/swaggo/files"
 	"github.com/swaggo/gin-swagger"
-	
+
 	"./docs" // docs is generated by Swag CLI, you have to import it.
 )
 
@@ -212,7 +212,7 @@ func main() {
 	docs.SwaggerInfo.Host = "petstore.swagger.io"
 	docs.SwaggerInfo.BasePath = "/v2"
 	docs.SwaggerInfo.Schemes = []string{"http", "https"}
-		
+
 	r := gin.New()
 
 	// use ginSwagger middleware to serve the API docs
@@ -298,10 +298,10 @@ $ swag init
 
 ## The swag formatter
 
-The Swag Comments can be automatically formatted, just like 'go fmt'.  
+The Swag Comments can be automatically formatted, just like 'go fmt'.
 Find the result of formatting [here](https://github.com/swaggo/swag/tree/master/example/celler).
 
-Usage: 
+Usage:
 ```shell
 swag fmt
 ```
@@ -444,11 +444,11 @@ Besides that, `swag` also accepts aliases for some MIME Types as follows:
 | 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                          | // @securityDefinitions.apikey ApiKeyAuth                    |
-| securitydefinitions.oauth2.application  | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, scope                   | // @securitydefinitions.oauth2.application OAuth2Application |
-| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | authorizationUrl, scope           | // @securitydefinitions.oauth2.implicit OAuth2Implicit       |
-| securitydefinitions.oauth2.password     | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | tokenUrl, scope                   | // @securitydefinitions.oauth2.password OAuth2Password       |
-| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, authorizationUrl, scope | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |
+| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth.            | in, name, sec.def.description                          | // @securityDefinitions.apikey ApiKeyAuth                    |
+| securitydefinitions.oauth2.application  | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, scope, sec.def.description                   | // @securitydefinitions.oauth2.application OAuth2Application |
+| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | authorizationUrl, scope, sec.def.description           | // @securitydefinitions.oauth2.implicit OAuth2Implicit       |
+| securitydefinitions.oauth2.password     | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth.          | tokenUrl, scope, sec.def.description                   | // @securitydefinitions.oauth2.password OAuth2Password       |
+| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth.       | tokenUrl, authorizationUrl, scope, sec.def.description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |
 
 
 | parameters annotation | example                                                  |
@@ -487,7 +487,7 @@ type Foo struct {
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="validate"></a>validate | `string` | 	Determines the validation for the parameter. Possible values are: `required`. 
+<a name="validate"></a>validate | `string` | 	Determines the validation for the parameter. Possible values are: `required`.
 <a name="parameterDefault"></a>default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.)  See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter.
 <a name="parameterMaximum"></a>maximum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
 <a name="parameterMinimum"></a>minimum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
@@ -512,7 +512,7 @@ Field Name | Type | Description
 
 ### Descriptions over multiple lines
 
-You can add descriptions spanning multiple lines in either the general api description or routes definitions like so: 
+You can add descriptions spanning multiple lines in either the general api description or routes definitions like so:
 
 ```go
 // @description This is the first line
@@ -561,7 +561,7 @@ type Order struct { //in `proto` package
 @success 200 {object} jsonresult.JSONResult{data=[]string} "desc"
 ```
 
-- overriding multiple fields. field will be added if not exists 
+- overriding multiple fields. field will be added if not exists
 ```go
 @success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
 ```
@@ -751,7 +751,7 @@ Rendered:
   "id": "integer"
 }
 ```
-    
+
 
 ### Use swaggerignore tag to exclude a field
 

parser.go

@@ -472,35 +472,45 @@ func parseGeneralAPIInfo(parser *Parser, comments []string) error {
 		case "@securitydefinitions.basic":
 			parser.swagger.SecurityDefinitions[value] = spec.BasicAuth()
 		case "@securitydefinitions.apikey":
-			attrMap, _, _, err := parseSecAttr(attribute, []string{"@in", "@name"}, comments[i+1:])
+			attrMap, _, extensions, err := parseSecAttr(attribute, []string{"@in", "@name"}, comments[i+1:])
 			if err != nil {
 				return err
 			}
-			parser.swagger.SecurityDefinitions[value] = spec.APIKeyAuth(attrMap["@name"], attrMap["@in"])
+			secDef := spec.APIKeyAuth(attrMap["@name"], attrMap["@in"])
+			tryAddDescription(secDef, extensions)
+			parser.swagger.SecurityDefinitions[value] = secDef
 		case "@securitydefinitions.oauth2.application":
 			attrMap, scopes, extensions, err := parseSecAttr(attribute, []string{"@tokenurl"}, comments[i+1:])
 			if err != nil {
 				return err
 			}
-			parser.swagger.SecurityDefinitions[value] = secOAuth2Application(attrMap["@tokenurl"], scopes, extensions)
+			secDef := secOAuth2Application(attrMap["@tokenurl"], scopes, extensions)
+			tryAddDescription(secDef, extensions)
+			parser.swagger.SecurityDefinitions[value] = secDef
 		case "@securitydefinitions.oauth2.implicit":
 			attrs, scopes, ext, err := parseSecAttr(attribute, []string{"@authorizationurl"}, comments[i+1:])
 			if err != nil {
 				return err
 			}
-			parser.swagger.SecurityDefinitions[value] = secOAuth2Implicit(attrs["@authorizationurl"], scopes, ext)
+			secDef := secOAuth2Implicit(attrs["@authorizationurl"], scopes, ext)
+			tryAddDescription(secDef, ext)
+			parser.swagger.SecurityDefinitions[value] = secDef
 		case "@securitydefinitions.oauth2.password":
 			attrs, scopes, ext, err := parseSecAttr(attribute, []string{"@tokenurl"}, comments[i+1:])
 			if err != nil {
 				return err
 			}
-			parser.swagger.SecurityDefinitions[value] = secOAuth2Password(attrs["@tokenurl"], scopes, ext)
+			secDef := secOAuth2Password(attrs["@tokenurl"], scopes, ext)
+			tryAddDescription(secDef, ext)
+			parser.swagger.SecurityDefinitions[value] = secDef
 		case "@securitydefinitions.oauth2.accesscode":
 			attrs, scopes, ext, err := parseSecAttr(attribute, []string{"@tokenurl", "@authorizationurl"}, comments[i+1:])
 			if err != nil {
 				return err
 			}
-			parser.swagger.SecurityDefinitions[value] = secOAuth2AccessToken(attrs["@authorizationurl"], attrs["@tokenurl"], scopes, ext)
+			secDef := secOAuth2AccessToken(attrs["@authorizationurl"], attrs["@tokenurl"], scopes, ext)
+			tryAddDescription(secDef, ext)
+			parser.swagger.SecurityDefinitions[value] = secDef
 		case "@query.collection.format":
 			parser.collectionFormatInQuery = value
 		default:
@@ -549,6 +559,14 @@ func parseGeneralAPIInfo(parser *Parser, comments []string) error {
 	return nil
 }
 
+func tryAddDescription(spec *spec.SecurityScheme, extensions map[string]interface{}) {
+	if val, ok := extensions["@sec.def.description"]; ok {
+		if str, ok := val.(string); ok {
+			spec.Description = str
+		}
+	}
+}
+
 // ParseAcceptComment parses comment for given `accept` comment string.
 func (parser *Parser) ParseAcceptComment(commentLine string) error {
 	return parseMimeTypeList(commentLine, &parser.swagger.Consumes, "%v accept type can't be accepted")
@@ -581,7 +599,6 @@ func parseSecAttr(context string, search []string, lines []string) (map[string]s
 		for _, findterm := range search {
 			if securityAttr == findterm {
 				attrMap[securityAttr] = strings.TrimSpace(v[len(securityAttr):])
-
 				continue
 			}
 		}
@@ -596,6 +613,10 @@ func parseSecAttr(context string, search []string, lines []string) (map[string]s
 			// Add the custom attribute without the @
 			extensions[securityAttr[1:]] = strings.TrimSpace(v[len(securityAttr):])
 		}
+		// Not mandatory field
+		if securityAttr == "@sec.def.description" {
+			extensions[securityAttr] = strings.TrimSpace(v[len(securityAttr):])
+		}
 		// next securityDefinitions
 		if strings.Index(securityAttr, "@securitydefinitions.") == 0 {
 			break

parser_test.go

@@ -538,12 +538,14 @@ func TestParser_ParseGeneralAPISecurity(t *testing.T) {
 		err := parseGeneralAPIInfo(parser, []string{
 			"@securitydefinitions.apikey ApiKey",
 			"@in header",
-			"@name X-API-KEY"})
+			"@name X-API-KEY",
+			"@sec.def.description some"})
 		assert.NoError(t, err)
 
 		b, _ := json.MarshalIndent(parser.GetSwagger().SecurityDefinitions, "", "    ")
 		expected := `{
     "ApiKey": {
+        "description": "some",
         "type": "apiKey",
         "name": "X-API-KEY",
         "in": "header"

swagger_test.go

@@ -146,6 +146,14 @@ var doc = `{
                 }
             }
         }
+    },
+    "securityDefinitions": {
+        "ApiKey": {
+            "description: "some",
+            "type": "apiKey",
+            "name": "X-API-KEY",
+            "in": "header"
+        }
     }
 }`