Expose experimental methods. (#379)

For parity with oxide.rs, expose experimental methods from the api,
prefixing paths with "Experimental" to indicate to users that the
methods may change.

Note: we could also indicate methods as being experimental by putting
them into a different package, or a different client, or just in their
docs. This seemed like the simplest approach that would still make the
intention clear to sdk users.

Author: jmcarp

internal/generate/paths.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"net/http"
 	"os"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
@@ -36,6 +37,7 @@ type methodTemplate struct {
 	HasBody         bool
 	HasSummary      bool
 	IsAppJSON       bool
+	IsExperimental  bool
 }
 
 type paramsInfo struct {
@@ -141,22 +143,24 @@ func buildMethod(
 		return nil
 	}
 
-	if o.Tags[0] == "experimental" {
-		fmt.Printf("[WARN] TODO: skipping operation %q, since it is experimental\n", o.OperationID)
-		return nil
-	}
-
-	if o.Tags[0] == "console-auth" {
+	if slices.Contains(o.Tags, "console-auth") {
 		fmt.Printf(
 			"[WARN] TODO: skipping operation %q, since it is for console authentication\n",
 			o.OperationID,
 		)
 		return nil
 	}
 
+	isExperimental := slices.Contains(o.Tags, "experimental")
+
 	methodName := strcase.ToCamel(o.OperationID)
 	pInfo := buildParams(o, methodName)
 
+	// Prefix experimental operations so callers know the API may change.
+	if isExperimental {
+		methodName = "Experimental" + methodName
+	}
+
 	// Adapt for ListAll methods
 
 	if isGetAllPages {
@@ -206,6 +210,7 @@ func buildMethod(
 		HasParams:       pInfo.paramsString != "",
 		HasSummary:      o.Summary != "",
 		HasDescription:  o.Description != "",
+		IsExperimental:  isExperimental,
 	}
 
 	// TODO: Handle other content types
@@ -426,7 +431,11 @@ func buildPathOrQueryParams(
 					fmt.Sprintf("%q: %s.Format(time.RFC3339),", name, n),
 				)
 			default:
-				pathParams = append(pathParams, fmt.Sprintf("%q: string(%s),", name, n))
+				if p.Schema.Value != nil && p.Schema.Value.Type.Is("integer") {
+					pathParams = append(pathParams, fmt.Sprintf("%q: fmt.Sprint(%s),", name, n))
+				} else {
+					pathParams = append(pathParams, fmt.Sprintf("%q: string(%s),", name, n))
+				}
 			}
 		}
 	}

internal/generate/templates/description.go.tpl

@@ -1,4 +1,6 @@
-{{define "description"}}// {{.FunctionName}}{{if .HasSummary}}: {{.Summary}}{{end}}{{if .HasDescription}}
+{{define "description"}}{{if .IsExperimental}}// EXPERIMENTAL: This operation is not yet stable and may change or be removed without notice.
+//
+{{end}}// {{.FunctionName}}{{if .HasSummary}}: {{.Summary}}{{end}}{{if .HasDescription}}
 // {{.Description}}{{end}}{{if .IsListAll}}
 //
 // This method is a wrapper around the `{{.WrappedFunction}}` method.