diff --git a/README.md b/README.md index 054e36ec6..6eb88561f 100644 --- a/README.md +++ b/README.md @@ -417,6 +417,7 @@ When a short string in your documentation is insufficient, or you need images, c | description.markdown | A short description of the application. Parsed from the api.md file. This is an alternative to @description |// @description.markdown No value needed, this parses the description from api.md | | tag.name | Name of a tag.| // @tag.name This is the name of the tag | | tag.description.markdown | Description of the tag this is an alternative to tag.description. The description will be read from a file named like tagname.md | // @tag.description.markdown | +| tag.x-name | The extension key, must be start by x- and take only string value | // @x-example-key value | ## API Operation diff --git a/parser.go b/parser.go index 561c4549e..5aa74e024 100644 --- a/parser.go +++ b/parser.go @@ -673,6 +673,21 @@ func parseGeneralAPIInfo(parser *Parser, comments []string) error { parser.swagger.Extensions[attribute[1:]] = valueJSON } + } else if strings.HasPrefix(attribute, "@tag.x-") { + extensionName := attribute[5:] + + if len(value) == 0 { + return fmt.Errorf("annotation %s need a value", attribute) + } + + if tag.Extensions == nil { + tag.Extensions = make(map[string]interface{}) + } + + // tag.Extensions.Add(extensionName, value) works wrong (transforms extensionName to lower case) + // needed to save case for ReDoc + // https://redocly.com/docs/api-reference-docs/specification-extensions/x-display-name/ + tag.Extensions[extensionName] = value } } diff --git a/parser_test.go b/parser_test.go index 7862796d1..7dc5e482f 100644 --- a/parser_test.go +++ b/parser_test.go @@ -576,7 +576,8 @@ func TestParser_ParseGeneralAPITagDocs(t *testing.T) { "@tag.name test", "@tag.description A test Tag", "@tag.docs.url https://example.com", - "@tag.docs.description Best example documentation"}) + "@tag.docs.description Best example documentation", + "@tag.x-displayName Test group"}) assert.NoError(t, err) b, _ := json.MarshalIndent(parser.GetSwagger().Tags, "", " ") @@ -587,7 +588,8 @@ func TestParser_ParseGeneralAPITagDocs(t *testing.T) { "externalDocs": { "description": "Best example documentation", "url": "https://example.com" - } + }, + "x-displayName": "Test group" } ]` assert.Equal(t, expected, string(b))