feat: support x-beta

pkg/cmd/generate/clients/clients.go

@@ -36,6 +36,7 @@ type ExternalDocs struct {
 type OperationData struct {
 	ACL              string
 	APIName          string
+	Beta             bool
 	CodeSamples      []CodeSample
 	Deprecated       bool
 	Description      string
@@ -152,8 +153,6 @@ func runCommand(opts *Options, printer *output.Printer) error {
 }
 
 // getAPIData reads the OpenAPI spec and parses the operation data.
-//
-//nolint:funlen
 func getAPIData(
 	doc *libopenapi.DocumentModel[v3.Document],
 	opts *Options,
@@ -162,6 +161,11 @@ func getAPIData(
 
 	count := 0
 
+	beta, err := utils.IsBetaAPI(&doc.Model)
+	if err != nil {
+		return nil, fmt.Errorf("get beta status: %w", err)
+	}
+
 	prefix := fmt.Sprintf("%s/%s", opts.OutputDirectory, opts.APIName)
 
 	for pathPairs := doc.Model.Paths.PathItems.First(); pathPairs != nil; pathPairs = pathPairs.Next() {
@@ -174,44 +178,16 @@ func getAPIData(
 		pathItem := pathPairs.Value()
 
 		for opPairs := pathItem.GetOperations().First(); opPairs != nil; opPairs = opPairs.Next() {
-			op := opPairs.Value()
-
-			acl, err := utils.GetACL(op)
+			data, err := buildOperationData(
+				opPairs.Key(),
+				pathName,
+				opPairs.Value(),
+				opts,
+				prefix,
+				beta,
+			)
 			if err != nil {
-				return nil, fmt.Errorf("get ACL for %s %s: %w", opPairs.Key(), pathName, err)
-			}
-
-			short, long := utils.SplitDescription(op.Description)
-			short = utils.StripMarkdown(short)
-
-			data := OperationData{
-				ACL:              utils.AclToString(acl),
-				APIName:          opts.APIName,
-				CodeSamples:      getCodeSamples(op),
-				Deprecated:       boolOrFalse(op.Deprecated),
-				Description:      long,
-				OutputFilename:   utils.GetOutputFilename(op),
-				OutputPath:       prefix,
-				OperationIDKebab: utils.ToKebabCase(op.OperationId),
-				Params:           getParameters(op),
-				RequiresAdmin:    false,
-				RequestBody:      getRequestBody(op),
-				ShortDescription: short,
-				Summary:          op.Summary,
-			}
-
-			if data.ACL == "`admin`" {
-				data.RequiresAdmin = true
-			}
-
-			if op.ExternalDocs != nil {
-				desc := strings.TrimSpace(op.ExternalDocs.Description)
-				data.ExternalDocs.Description = strings.TrimSuffix(desc, ".")
-				data.ExternalDocs.URL = op.ExternalDocs.URL
-			}
-
-			if data.ExternalDocs.Description != "" && data.ExternalDocs.URL != "" {
-				data.SeeAlso = true
+				return nil, err
 			}
 
 			result = append(result, data)
@@ -222,6 +198,60 @@ func getAPIData(
 	return result, nil
 }
 
+func buildOperationData(
+	verb, pathName string,
+	op *v3.Operation,
+	opts *Options,
+	prefix string,
+	beta bool,
+) (OperationData, error) {
+	opBeta, err := utils.IsBetaOperation(op)
+	if err != nil {
+		return OperationData{}, fmt.Errorf("get beta status for %s %s: %w", verb, pathName, err)
+	}
+
+	acl, err := utils.GetACL(op)
+	if err != nil {
+		return OperationData{}, fmt.Errorf("get ACL for %s %s: %w", verb, pathName, err)
+	}
+
+	short, long := utils.SplitDescription(op.Description)
+	short = utils.StripMarkdown(short)
+
+	data := OperationData{
+		ACL:              utils.AclToString(acl),
+		APIName:          opts.APIName,
+		Beta:             beta || opBeta,
+		CodeSamples:      getCodeSamples(op),
+		Deprecated:       boolOrFalse(op.Deprecated),
+		Description:      long,
+		OutputFilename:   utils.GetOutputFilename(op),
+		OutputPath:       prefix,
+		OperationIDKebab: utils.ToKebabCase(op.OperationId),
+		Params:           getParameters(op),
+		RequiresAdmin:    false,
+		RequestBody:      getRequestBody(op),
+		ShortDescription: short,
+		Summary:          op.Summary,
+	}
+
+	if data.ACL == "`admin`" {
+		data.RequiresAdmin = true
+	}
+
+	if op.ExternalDocs != nil {
+		desc := strings.TrimSpace(op.ExternalDocs.Description)
+		data.ExternalDocs.Description = strings.TrimSuffix(desc, ".")
+		data.ExternalDocs.URL = op.ExternalDocs.URL
+	}
+
+	if data.ExternalDocs.Description != "" && data.ExternalDocs.URL != "" {
+		data.SeeAlso = true
+	}
+
+	return data, nil
+}
+
 // writeAPIData writes the OpenAPI data to MDX files.
 func writeAPIData(
 	data []OperationData,

pkg/cmd/generate/clients/clients_test.go

@@ -26,6 +26,7 @@ paths:
         Use the [API key](https://algolia.com) endpoint with **filters:active**.
 
         This body keeps [markdown](https://algolia.com/doc) and **details** intact.
+      x-beta: true
       x-acl:
         - search
 `)
@@ -78,6 +79,8 @@ paths:
 	assertFrontmatterDescription(t, frontmatter, "Use the API key endpoint with filters:active.")
 
 	assertRenderedContains(t, rendered.String(), []string{
+		`import Beta from "/snippets/beta.mdx";`,
+		"<Beta />",
 		`description: "Use the API key endpoint with filters:active."`,
 		"This body keeps [markdown](https://algolia.com/doc) and **details** intact.",
 		"**Required ACL:** `search`",

pkg/cmd/generate/clients/method.mdx.tmpl

@@ -3,6 +3,12 @@ title: {{ .Summary }}
 description: {{ frontmatterString .ShortDescription }}
 public: true
 ---
+{{- if .Beta }}
+
+import Beta from "/snippets/beta.mdx";
+
+<Beta />
+{{- end }}
 {{- if .Deprecated }}
 
 <Warning>This method is **deprecated.**</Warning>

pkg/cmd/generate/openapi/openapi.go

@@ -44,6 +44,7 @@ type OverviewData struct {
 type OperationData struct {
 	ACL              string
 	APIPath          string
+	Beta             bool
 	Description      string
 	ExternalDocs     ExternalDocs
 	InputFilename    string
@@ -187,6 +188,11 @@ func getAPIData(
 
 	count := 0
 
+	beta, err := utils.IsBetaAPI(&doc.Model)
+	if err != nil {
+		return nil, fmt.Errorf("get beta status: %w", err)
+	}
+
 	prefix := fmt.Sprintf("%s/%s", opts.OutputDirectory, opts.APIName)
 
 	for pathPairs := doc.Model.Paths.PathItems.First(); pathPairs != nil; pathPairs = pathPairs.Next() {
@@ -199,7 +205,14 @@ func getAPIData(
 		pathItem := pathPairs.Value()
 
 		for opPairs := pathItem.GetOperations().First(); opPairs != nil; opPairs = opPairs.Next() {
-			data, err := buildOperationData(opPairs.Key(), pathName, opPairs.Value(), opts, prefix)
+			data, err := buildOperationData(
+				opPairs.Key(),
+				pathName,
+				opPairs.Value(),
+				opts,
+				prefix,
+				beta,
+			)
 			if err != nil {
 				return nil, err
 			}
@@ -217,6 +230,7 @@ func buildOperationData(
 	op *v3.Operation,
 	opts *Options,
 	prefix string,
+	beta bool,
 ) (OperationData, error) {
 	short, long := utils.SplitDescription(op.Description)
 
@@ -225,9 +239,15 @@ func buildOperationData(
 		return OperationData{}, fmt.Errorf("get ACL for %s %s: %w", verb, pathName, err)
 	}
 
+	opBeta, err := utils.IsBetaOperation(op)
+	if err != nil {
+		return OperationData{}, fmt.Errorf("get beta status for %s %s: %w", verb, pathName, err)
+	}
+
 	data := OperationData{
 		ACL:              utils.AclToString(acl),
 		APIPath:          pathName,
+		Beta:             beta || opBeta,
 		Description:      long,
 		InputFilename:    normalizePath(opts.InputFileName),
 		OutputFilename:   utils.GetOutputFilename(op),

pkg/cmd/generate/openapi/openapi_test.go

@@ -26,6 +26,7 @@ paths:
         Retrieve the [API key](https://algolia.com) with **filters:active**.
 
         Use this endpoint to fetch a key by its value with **sample** output.
+      x-beta: true
       x-acl:
         - search
 `)
@@ -75,6 +76,8 @@ paths:
 	assertFrontmatterDescription(t, frontmatter, "Retrieve the API key with filters:active.")
 
 	assertRenderedContains(t, rendered, []string{
+		`import Beta from "/snippets/beta.mdx";`,
+		"<Beta />",
 		"title: Get an API key",
 		`description: "Retrieve the API key with filters:active."`,
 		"Use this endpoint to fetch a key by its value with **sample** output.",

pkg/cmd/generate/openapi/stub.mdx.tmpl

@@ -4,6 +4,12 @@ description: {{ frontmatterString .ShortDescription }}
 openapi: {{ .InputFilename }} {{ .Verb }} {{ .APIPath }}
 public: true
 ---
+{{- if .Beta }}
+
+import Beta from "/snippets/beta.mdx";
+
+<Beta />
+{{- end }}
 {{- if .Description }}
 
 {{ .Description }}

pkg/cmd/generate/utils/utils.go

@@ -54,6 +54,47 @@ func GetAPIName(path string) string {
 	return strings.TrimSuffix(base, filepath.Ext(base))
 }
 
+// IsBetaAPI returns true if the root document has an `x-beta: true` extension.
+func IsBetaAPI(doc *v3.Document) (bool, error) {
+	if doc.Extensions == nil {
+		return false, nil
+	}
+
+	node, ok := doc.Extensions.Get("x-beta")
+	if !ok {
+		return false, nil
+	}
+
+	return parseBetaNode(node)
+}
+
+// IsBetaOperation returns true if the operation has an `x-beta: true` extension.
+func IsBetaOperation(op *v3.Operation) (bool, error) {
+	if op.Extensions == nil {
+		return false, nil
+	}
+
+	node, ok := op.Extensions.Get("x-beta")
+	if !ok {
+		return false, nil
+	}
+
+	return parseBetaNode(node)
+}
+
+func parseBetaNode(node *yaml.Node) (bool, error) {
+	if node.Kind != yaml.ScalarNode {
+		return false, fmt.Errorf("expected a scalar node, got kind %d", node.Kind)
+	}
+
+	var result bool
+	if err := node.Decode(&result); err != nil {
+		return false, fmt.Errorf("expected a boolean node: %w", err)
+	}
+
+	return result, nil
+}
+
 // GetACL returns the ACL required to perform the given operation.
 func GetACL(op *v3.Operation) ([]string, error) {
 	node, ok := op.Extensions.Get("x-acl")