feat(generate): allow generating Server URL boilerplate

When working with a client generated by `oapi-codegen`, it can be a
little awkward to manage changing URLs for the `client.WithBaseURL`.

Although it's possible to manage these ourselves - with hardcoded values
- it can be handy to have this pre-generated, especially if the input
spec already defines `$.servers`.

This introduces the capability to opt-in to the generation (as we try to
make all changes opt-in where possible) of these.

This is a little more complicated than ""just"" generating constants, as
a Server object could introduce a templated URL.

This requires we:

- generate the `const`s for non-templated URLs
- generate the more in-depth boilerplate for templated URLs

We try and do most of the generating in the template, rather than in Go
code, although it's not straightforward to generate the method
parameters for the generated function (i.e.
`NewServerUrlTheProductionAPIServer`) so we create a
`genServerURLWithVariablesFunctionParams` function.

We'll leave a few cases of additional validation or handling of edge
cases to a follow-up.

Author: jamietanna

README.md

@@ -1731,6 +1731,71 @@ func TestClient_canCall() {
 }
 ```
 
+### With Server URLs
+
+An OpenAPI specification makes it possible to denote Servers that a client can interact with, such as:
+
+```yaml
+servers:
+- url: https://development.gigantic-server.com/v1
+  description: Development server
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+  description: The production API server
+  variables:
+    username:
+      # note! no enum here means it is an open value
+      default: demo
+      description: this value is assigned by the service provider, in this example `gigantic-server.com`
+    port:
+      enum:
+        - '8443'
+        - '443'
+      default: '8443'
+    basePath:
+      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+      default: v2
+```
+
+It is possible to opt-in to the generation of these Server URLs with the following configuration:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
+package: serverurls
+output: gen.go
+generate:
+  # NOTE that this uses default settings - if you want to use initialisms to generate i.e. `ServerURLDevelopmentServer`, you should look up the `output-options.name-normalizer` configuration
+  server-urls: true
+```
+
+This will then generate the following boilerplate:
+
+```go
+// (the below does not include comments that are generated)
+
+const ServerUrlDevelopmentServer = "https://development.gigantic-server.com/v1"
+
+type ServerUrlTheProductionAPIServerBasePathVariable string
+const ServerUrlTheProductionAPIServerBasePathVariableDefault = "v2"
+
+type ServerUrlTheProductionAPIServerPortVariable string
+const ServerUrlTheProductionAPIServerPortVariable8443 ServerUrlTheProductionAPIServerPortVariable = "8443"
+const ServerUrlTheProductionAPIServerPortVariable443 ServerUrlTheProductionAPIServerPortVariable = "443"
+const ServerUrlTheProductionAPIServerPortVariableDefault ServerUrlTheProductionAPIServerPortVariable = ServerUrlTheProductionAPIServerPortVariable8443
+
+type ServerUrlTheProductionAPIServerUsernameVariable string
+const ServerUrlTheProductionAPIServerUsernameVariableDefault = "demo"
+
+func ServerUrlTheProductionAPIServer(basePath ServerUrlTheProductionAPIServerBasePathVariable, port ServerUrlTheProductionAPIServerPortVariable, username ServerUrlTheProductionAPIServerUsernameVariable) (string, error) {
+    // ...
+}
+```
+
+Notice that for URLs that are not templated, a simple `const` definition is created.
+
+However, for more complex URLs that defined `variables` in them, we generate the types (and any `enum` values or `default` values), and instead use a function to create the URL.
+
+For a complete example see [`examples/generate/serverurls`](examples/generate/serverurls).
+
 ## Generating API models
 
 If you're looking to only generate the models for interacting with a remote service, for instance if you need to hand-roll the API client for whatever reason, you can do this as-is.

configuration-schema.json

@@ -56,6 +56,10 @@
         "embedded-spec": {
           "type": "boolean",
           "description": "EmbeddedSpec indicates whether to embed the swagger spec in the generated code"
+        },
+        "server-urls": {
+          "type": "boolean",
+          "description": "Generate types for the `Server` definitions' URLs, instead of needing to provide your own values"
         }
       }
     },

examples/generate/serverurls/api.yaml

@@ -0,0 +1,47 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Server URLs can be optionally generated
+servers:
+# adapted from https://spec.openapis.org/oas/v3.0.3#server-object
+- url: https://development.gigantic-server.com/v1
+  description: Development server
+- url: https://staging.gigantic-server.com/v1
+  description: Staging server
+- url: https://api.gigantic-server.com/v1
+  description: Production server
+# adapted from https://spec.openapis.org/oas/v3.0.3#server-object
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+  description: The production API server
+  variables:
+    username:
+      # note! no enum here means it is an open value
+      default: demo
+      description: this value is assigned by the service provider, in this example `gigantic-server.com`
+    port:
+      enum:
+        - '8443'
+        - '443'
+      default: '8443'
+    basePath:
+      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+      default: v2
+    # an example of a type that's defined, but doesn't have a default
+    noDefault: {}
+    # # TODO this conflict will cause broken generated code https://github.com/oapi-codegen/oapi-codegen/issues/2003
+    # conflicting:
+    #   enum:
+    #     - 'default'
+    #     - '443'
+    #   default: 'default'
+# clash with the previous definition of `Development server` to trigger a new name
+- url: http://localhost:80
+  description: Development server
+# clash with the previous definition of `Development server` to trigger a new name (again)
+- url: http://localhost:80
+  description: Development server
+# make sure that the lowercase `description` gets converted to an uppercase
+- url: http://localhost:80
+  description: some lowercase name
+# there may be URLs on their own, without a `description`
+- url: http://localhost:443

examples/generate/serverurls/cfg.yaml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=../../../configuration-schema.json
+package: serverurls
+output: gen.go
+generate:
+  server-urls: true
+output-options:
+  # to make sure that all types are generated, even if they're unreferenced
+  skip-prune: true

examples/generate/serverurls/gen.go

@@ -0,0 +1,48 @@
+package serverurls
+
+import (
+	"net/url"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestServerUrlTheProductionAPIServer(t *testing.T) {
+	t.Run("when no values are provided, it does not error", func(t *testing.T) {
+		serverUrl, err := NewServerUrlTheProductionAPIServer("", "", "", "")
+		require.NoError(t, err)
+
+		assert.Equal(t, "https://.gigantic-server.com:/", serverUrl)
+
+		// NOTE that ideally this should fail as it doesn't /seem/ to provide a valid URL, but it does seem to be valid
+		_, err = url.Parse(serverUrl)
+		require.NoError(t, err)
+	})
+
+	// TODO:when we validate enums, this will need more testing https://github.com/oapi-codegen/oapi-codegen/issues/2006
+	t.Run("when values that are not part of the enum are provided, it does not error", func(t *testing.T) {
+		invalidPort := ServerUrlTheProductionAPIServerPortVariable("12345")
+		serverUrl, err := NewServerUrlTheProductionAPIServer(
+			ServerUrlTheProductionAPIServerBasePathVariableDefault,
+			ServerUrlTheProductionAPIServerNoDefaultVariable(""),
+			invalidPort,
+			ServerUrlTheProductionAPIServerUsernameVariableDefault,
+		)
+		require.NoError(t, err)
+
+		assert.Equal(t, "https://demo.gigantic-server.com:12345/v2", serverUrl)
+	})
+
+	t.Run("when default values are provided, it does not error", func(t *testing.T) {
+		serverUrl, err := NewServerUrlTheProductionAPIServer(
+			ServerUrlTheProductionAPIServerBasePathVariableDefault,
+			ServerUrlTheProductionAPIServerNoDefaultVariable(""),
+			ServerUrlTheProductionAPIServerPortVariableDefault,
+			ServerUrlTheProductionAPIServerUsernameVariableDefault,
+		)
+		require.NoError(t, err)
+
+		assert.Equal(t, "https://demo.gigantic-server.com:8443/v2", serverUrl)
+	})
+}

examples/generate/serverurls/gen_test.go

@@ -0,0 +1,3 @@
+package serverurls
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml

examples/generate/serverurls/generate.go

@@ -202,6 +202,14 @@ func Generate(spec *openapi3.T, opts Configuration) (string, error) {
 		MergeImports(xGoTypeImports, imprts)
 	}
 
+	var serverURLsDefinitions string
+	if opts.Generate.ServerURLs {
+		serverURLsDefinitions, err = GenerateServerURLs(t, spec)
+		if err != nil {
+			return "", fmt.Errorf("error generating Server URLs: %w", err)
+		}
+	}
+
 	var irisServerOut string
 	if opts.Generate.IrisServer {
 		irisServerOut, err = GenerateIrisServer(t, ops)
@@ -326,6 +334,11 @@ func Generate(spec *openapi3.T, opts Configuration) (string, error) {
 		return "", fmt.Errorf("error writing constants: %w", err)
 	}
 
+	_, err = w.WriteString(serverURLsDefinitions)
+	if err != nil {
+		return "", fmt.Errorf("error writing Server URLs: %w", err)
+	}
+
 	_, err = w.WriteString(typeDefinitions)
 	if err != nil {
 		return "", fmt.Errorf("error writing type definitions: %w", err)

pkg/codegen/codegen.go

@@ -126,6 +126,8 @@ type GenerateOptions struct {
 	Models bool `yaml:"models,omitempty"`
 	// EmbeddedSpec indicates whether to embed the swagger spec in the generated code
 	EmbeddedSpec bool `yaml:"embedded-spec,omitempty"`
+	// ServerURLs generates types for the `Server` definitions' URLs, instead of needing to provide your own values
+	ServerURLs bool `yaml:"server-urls,omitempty"`
 }
 
 func (oo GenerateOptions) Validate() map[string]string {

pkg/codegen/configuration.go

@@ -0,0 +1,81 @@
+package codegen
+
+import (
+	"fmt"
+	"strconv"
+	"text/template"
+
+	"github.com/getkin/kin-openapi/openapi3"
+)
+
+const serverURLPrefix = "ServerUrl"
+const serverURLSuffixIterations = 10
+
+// ServerObjectDefinition defines the definition of an OpenAPI Server object (https://spec.openapis.org/oas/v3.0.3#server-object) as it is provided to code generation in `oapi-codegen`
+type ServerObjectDefinition struct {
+	// GoName is the name of the variable for this Server URL
+	GoName string
+
+	// OAPISchema is the underlying OpenAPI representation of the Server
+	OAPISchema *openapi3.Server
+}
+
+func GenerateServerURLs(t *template.Template, spec *openapi3.T) (string, error) {
+	names := make(map[string]*openapi3.Server)
+
+	for _, server := range spec.Servers {
+		suffix := server.Description
+		if suffix == "" {
+			suffix = nameNormalizer(server.URL)
+		}
+		name := serverURLPrefix + UppercaseFirstCharacter(suffix)
+		name = nameNormalizer(name)
+
+		// if this is the only type with this name, store it
+		if _, conflict := names[name]; !conflict {
+			names[name] = server
+			continue
+		}
+
+		// otherwise, try appending a number to the name
+		saved := false
+		// NOTE that we start at 1 on purpose, as
+		//
+		//  ... ServerURLDevelopmentServer
+		//  ... ServerURLDevelopmentServer1`
+		//
+		// reads better than:
+		//
+		//  ... ServerURLDevelopmentServer
+		//  ... ServerURLDevelopmentServer0
+		for i := 1; i < 1+serverURLSuffixIterations; i++ {
+			suffixed := name + strconv.Itoa(i)
+			// and then store it if there's no conflict
+			if _, suffixConflict := names[suffixed]; !suffixConflict {
+				names[suffixed] = server
+				saved = true
+				break
+			}
+		}
+
+		if saved {
+			continue
+		}
+
+		// otherwise, error
+		return "", fmt.Errorf("failed to create a unique name for the Server URL (%#v) with description (%#v) after %d iterations", server.URL, server.Description, serverURLSuffixIterations)
+	}
+
+	keys := SortedMapKeys(names)
+	servers := make([]ServerObjectDefinition, len(keys))
+	i := 0
+	for _, k := range keys {
+		servers[i] = ServerObjectDefinition{
+			GoName:     k,
+			OAPISchema: names[k],
+		}
+		i++
+	}
+
+	return GenerateTemplates([]string{"server-urls.tmpl"}, t, servers)
+}