V2: Add Servers param (#1573)

* Fix template delims

* go mod tidy

* Add basic implementation of the servers object

---------

Co-authored-by: Tobias Theel <tt@fino.digital>

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