V2: Add Servers param (#1573)

* Fix template delims

* go mod tidy

* Add basic implementation of the servers object

---------

Co-authored-by: Tobias Theel <[email protected]>

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
 

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)

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)
+
+}

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 [email protected]
+
+// @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)
+}