Skip to content

Commit

Permalink
Support externalDocs annotation comment (#1468)
Browse files Browse the repository at this point in the history
* Support externalDocs annotation comment

* Add unit test and update readme

* Change implement way for passing unit test
ikrisliu authored Feb 16, 2023
1 parent aa3e8d5 commit 37f466e
Showing 6 changed files with 38 additions and 0 deletions.
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -165,6 +165,9 @@ import "github.com/swaggo/files" // swagger embed files
// @BasePath /api/v1
// @securityDefinitions.basic BasicAuth
// @externalDocs.description OpenAPI
// @externalDocs.url https://swagger.io/resources/open-api/
func main() {
r := gin.Default()
@@ -386,6 +389,8 @@ func (c *Controller) ListAccounts(ctx *gin.Context) {
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). | // @produce json |
| query.collection.format | The default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default.| // @query.collection.format multi
| 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/ |
| x-name | The extension key, must be start by x- and take only json value | // @x-example-key {"key": "value"} |
### Using markdown descriptions
5 changes: 5 additions & 0 deletions README_zh-CN.md
Original file line number Diff line number Diff line change
@@ -158,6 +158,9 @@ import "github.com/swaggo/files" // swagger embed files
// @BasePath /api/v1

// @securityDefinitions.basic BasicAuth

// @externalDocs.description OpenAPI
// @externalDocs.url https://swagger.io/resources/open-api/
func main() {
r := gin.Default()

@@ -356,6 +359,8 @@ swag fmt -d ./ --exclude ./internal
| produce | API可以生成的MIME类型的列表。值必须如“[Mime类型](#mime类型)”中所述。 | // @produce json |
| query.collection.format | 请求URI query里数组参数的默认格式:csv,multi,pipes,tsv,ssv。 如果未设置,则默认为csv。 | // @query.collection.format multi |
| schemes | 用空格分隔的请求的传输协议。 | // @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/ |
| x-name | 扩展的键必须以x-开头,并且只能使用json值 | // @x-example-key {"key": "value"} |

### 使用Markdown描述
14 changes: 14 additions & 0 deletions parser.go
Original file line number Diff line number Diff line change
@@ -62,6 +62,8 @@ const (
secPasswordAttr = "@securitydefinitions.oauth2.password"
secAccessCodeAttr = "@securitydefinitions.oauth2.accesscode"
tosAttr = "@termsofservice"
extDocsDescAttr = "@externaldocs.description"
extDocsURLAttr = "@externaldocs.url"
xCodeSamplesAttr = "@x-codesamples"
scopeAttrPrefix = "@scope."
)
@@ -561,6 +563,18 @@ func parseGeneralAPIInfo(parser *Parser, comments []string) error {

case "@query.collection.format":
parser.collectionFormatInQuery = TransToValidCollectionFormat(value)

case extDocsDescAttr, extDocsURLAttr:
if parser.swagger.ExternalDocs == nil {
parser.swagger.ExternalDocs = new(spec.ExternalDocumentation)
}
switch attr {
case extDocsDescAttr:
parser.swagger.ExternalDocs.Description = value
case extDocsURLAttr:
parser.swagger.ExternalDocs.URL = value
}

default:
if strings.HasPrefix(attribute, "@x-") {
extensionName := attribute[1:]
8 changes: 8 additions & 0 deletions parser_test.go
Original file line number Diff line number Diff line change
@@ -253,6 +253,10 @@ func TestParser_ParseGeneralApiInfo(t *testing.T) {
}
}
},
"externalDocs": {
"description": "OpenAPI",
"url": "https://swagger.io/resources/open-api"
},
"x-google-endpoints": [
{
"allowCors": true,
@@ -338,6 +342,10 @@ func TestParser_ParseGeneralApiInfoTemplated(t *testing.T) {
}
}
},
"externalDocs": {
"description": "OpenAPI",
"url": "https://swagger.io/resources/open-api"
},
"x-google-endpoints": [
{
"allowCors": true,
3 changes: 3 additions & 0 deletions testdata/main.go
Original file line number Diff line number Diff line change
@@ -46,6 +46,9 @@ package main
// @scope.admin Grants read and write access to administrative information
// @x-tokenname id_token

// @externalDocs.description OpenAPI
// @externalDocs.url https://swagger.io/resources/open-api

// @x-google-endpoints [{"name":"name.endpoints.environment.cloud.goog","allowCors":true}]
// @x-google-marks "marks values"
// @x-logo {"url":"https://redocly.github.io/redoc/petstore-logo.png", "altText": "Petstore logo", "backgroundColor": "#FFFFFF"}
3 changes: 3 additions & 0 deletions testdata/templated.go
Original file line number Diff line number Diff line change
@@ -36,6 +36,9 @@ package main
// @authorizationurl https://example.com/oauth/authorize
// @scope.admin Grants read and write access to administrative information

// @externalDocs.description OpenAPI
// @externalDocs.url https://swagger.io/resources/open-api

// @x-google-endpoints [{"name":"name.endpoints.environment.cloud.goog","allowCors":true}]
// @x-google-marks "marks values"

0 comments on commit 37f466e

Please sign in to comment.