diff --git a/README.md b/README.md index c9ef0effd..69e963187 100644 --- a/README.md +++ b/README.md @@ -407,6 +407,14 @@ When a short string in your documentation is insufficient, or you need images, c | 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 | +## Open API V3.1.0+ + +The following annotations are only available if you set the -v3.1 flag in the CLI. + +| annotation | description | example | +|-------------|--------------------------------------------|---------------------------------| +| servers.url | The URL of a server| // @servers.url https://petstore.example.com/api/v1 | +| servers.description | The description of a server| // @servers.description Production API | ## API Operation diff --git a/parserv3.go b/parserv3.go index d71e69050..fa494c8c7 100644 --- a/parserv3.go +++ b/parserv3.go @@ -164,6 +164,22 @@ func (p *Parser) parseGeneralAPIInfoV3(comments []string) error { } p.openAPI.Info.Extensions[originalAttribute[1:]] = valueJSON + case "@servers.url": + server := spec.NewServer() + server.Spec.URL = value + + p.openAPI.Servers = append(p.openAPI.Servers, server) + case "@servers.description": + server := p.openAPI.Servers[len(p.openAPI.Servers)-1] + server.Spec.Description = value + case "@servers.variables.enum": + p.debug.Printf("not yet implemented: @servers.variables.enum") + case "@servers.variables.default": + p.debug.Printf("not yet implemented: @servers.variables.default") + case "@servers.variables.description": + p.debug.Printf("not yet implemented: @servers.variables.description") + case "@servers.variables.description.markdown": + p.debug.Printf("not yet implemented: @servers.variables.description.markdown") default: if strings.HasPrefix(attribute, "@x-") { err := p.parseExtensionsV3(value, attribute) diff --git a/parserv3_test.go b/parserv3_test.go index b889188cf..2511ca6ce 100644 --- a/parserv3_test.go +++ b/parserv3_test.go @@ -6,6 +6,7 @@ import ( "testing" "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" ) func TestOverridesGetTypeSchemaV3(t *testing.T) { @@ -370,3 +371,25 @@ func TestParseSimpleApiV3(t *testing.T) { assert.NotNil(t, path.RequestBody) //TODO add asserts } + +func TestParserParseServers(t *testing.T) { + t.Parallel() + + searchDir := "testdata/v3/servers" + p := New(GenerateOpenAPI3Doc(true)) + p.PropNamingStrategy = PascalCase + + err := p.ParseAPI(searchDir, mainAPIFile, defaultParseDepth) + assert.NoError(t, err) + + servers := p.openAPI.Servers + require.NotNil(t, servers) + + assert.Equal(t, 2, len(servers)) + assert.Equal(t, "https://test.petstore.com/v3", servers[0].Spec.URL) + assert.Equal(t, "Test Petstore server.", servers[0].Spec.Description) + + assert.Equal(t, "https://petstore.com/v3", servers[1].Spec.URL) + assert.Equal(t, "Production Petstore server.", servers[1].Spec.Description) + +} diff --git a/testdata/v3/servers/main.go b/testdata/v3/servers/main.go new file mode 100644 index 000000000..7820c34e8 --- /dev/null +++ b/testdata/v3/servers/main.go @@ -0,0 +1,32 @@ +package main + +import ( + "net/http" + + "github.com/swaggo/swag/v2/testdata/v3/simple/api" +) + +// @title Swagger Example API +// @version 1.0 +// @description This is a sample server Petstore server. +// @termsOfService http://swagger.io/terms/ + +// @contact.name API Support +// @contact.url http://www.swagger.io/support +// @contact.email support@swagger.io + +// @license.name Apache 2.0 +// @license.url http://www.apache.org/licenses/LICENSE-2.0.html + +// @servers.url https://test.petstore.com/v3 +// @servers.description Test Petstore server. + +// @servers.url https://petstore.com/v3 +// @servers.description Production Petstore server. +func main() { + http.HandleFunc("/testapi/get-string-by-int/", api.GetStringByInt) + http.HandleFunc("/testapi/get-struct-array-by-string/", api.GetStructArrayByString) + http.HandleFunc("/testapi/upload", api.Upload) + + http.ListenAndServe(":8080", nil) +}