Skip to content

Improve resources command: fix help text and add descriptions #1609

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gfscott wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Improve resources command: fix help text and add descriptions #1609

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
af52cda
Fix incorrect help text in resources command hint
gfscott May 25, 2026
fcfacfb
Add descriptions to resource commands from OpenAPI spec
gfscott May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions pkg/cmd/resource/resource.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,16 @@ func GetResourceCmdName(name string) string {
}
}

// NewResourceCmd returns a new ResourceCmd.
func NewResourceCmd(parentCmd *cobra.Command, resourceName string) *ResourceCmd {
// NewResourceCmd returns a new ResourceCmd. An optional description can be
// passed to set the Short help text for the command.
func NewResourceCmd(parentCmd *cobra.Command, resourceName string, description ...string) *ResourceCmd {
cmd := &cobra.Command{
Use: resourceName,
Annotations: make(map[string]string),
}
if len(description) > 0 && description[0] != "" {
cmd.Short = description[0]
}
cmd.SetUsageTemplate(resourceUsageTemplate())

parentCmd.AddCommand(cmd)
Expand Down
354 changes: 177 additions & 177 deletions pkg/cmd/resources/resources_gen.go
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions pkg/cmd/resources_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,8 @@ func TestResourcesListAliasedName(t *testing.T) {

aliases := resource.GetAliases()
for principle, alias := range aliases {
aliasRegexp := fmt.Sprintf("\n\\s+%s(s?)\\s+\n", resource.GetResourceCmdName(alias))
principleRegexp := fmt.Sprintf("\n\\s+%s(s?)\\s+\n", resource.GetResourceCmdName(principle))
aliasRegexp := fmt.Sprintf(`\n\s+%s(s?)\s+[^\n]*\n`, resource.GetResourceCmdName(alias))
principleRegexp := fmt.Sprintf(`\n\s+%s(s?)\s+[^\n]*\n`, resource.GetResourceCmdName(principle))
assert.Regexp(t, regexp.MustCompile(aliasRegexp), output)
assert.NotRegexp(t, regexp.MustCompile(principleRegexp), output)
}
Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/templates.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,7 @@ Use "{{.CommandPath}} [command] --help" for more information about a command.{{e
ansi.Bold("Webhook commands:"),
ansi.Bold("Stripe commands:"),
ansi.Bold("Resource commands:"),
ansi.Italic("To see more resource commands, run `stripe resources help`"),
ansi.Italic("To see more resource commands, run `stripe resources --help`"),
ansi.Italic("To see only v2 resource commands, run `stripe v2 help`"),
ansi.Bold("API commands:"),
ansi.Bold("Other commands:"),
Expand Down
11 changes: 7 additions & 4 deletions pkg/gen/gen_resources_cmds.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ type NamespaceData struct {
type ResourceData struct {
Operations map[string]*OperationData
SubResources map[string]*ResourceData
Description string
}

type OperationData struct {
Expand Down Expand Up @@ -260,6 +261,7 @@ func getApiNamespaceFromOperations(ops *[]spec.StripeOperation, isPreview bool)
func genCmdTemplate(apiNamespace ApiNamespace, schemaName string, cmdName string, data *TemplateData, stripeAPI *spec.Spec) error {
origNsName, origResName := parseSchemaName(cmdName)
schema := stripeAPI.Components.Schemas[schemaName]
resDescription := gen.CleanDescription(gen.FirstSentence(schema.Description))

for _, op := range *schema.XStripeOperations {
if op.MethodOn != "service" {
Expand All @@ -276,12 +278,12 @@ func genCmdTemplate(apiNamespace ApiNamespace, schemaName string, cmdName string
subResName = components[1]
} else if strings.Contains(op.Path, test_helpers_path) && test_helpers_path != nsName {
if nsName != "" {
err := addToTemplateData(data, apiNamespace, test_helpers_path, nsName, resName, stripeAPI, op)
err := addToTemplateData(data, apiNamespace, test_helpers_path, nsName, resName, stripeAPI, op, "")
if err != nil {
return err
}
} else {
err := addToTemplateData(data, apiNamespace, test_helpers_path, resName, "", stripeAPI, op)
err := addToTemplateData(data, apiNamespace, test_helpers_path, resName, "", stripeAPI, op, "")
if err != nil {
return err
}
Expand All @@ -290,7 +292,7 @@ func genCmdTemplate(apiNamespace ApiNamespace, schemaName string, cmdName string
subResName = test_helpers_path
}

err := addToTemplateData(data, apiNamespace, nsName, resName, subResName, stripeAPI, op)
err := addToTemplateData(data, apiNamespace, nsName, resName, subResName, stripeAPI, op, resDescription)
if err != nil {
return err
}
Expand All @@ -299,7 +301,7 @@ func genCmdTemplate(apiNamespace ApiNamespace, schemaName string, cmdName string
return nil
}

func addToTemplateData(data *TemplateData, apiNamespace ApiNamespace, nsName, resName, subResName string, stripeAPI *spec.Spec, op spec.StripeOperation) error {
func addToTemplateData(data *TemplateData, apiNamespace ApiNamespace, nsName, resName, subResName string, stripeAPI *spec.Spec, op spec.StripeOperation, resDescription string) error {
hasSubResources := subResName != ""

if _, ok := data.ApiNamespaces[apiNamespace]; !ok {
Expand All @@ -319,6 +321,7 @@ func addToTemplateData(data *TemplateData, apiNamespace ApiNamespace, nsName, re
data.ApiNamespaces[apiNamespace].Namespaces[nsName].Resources[resCmdName] = &ResourceData{
Operations: make(map[string]*OperationData),
SubResources: make(map[string]*ResourceData),
Description: resDescription,
}
}

Expand Down
17 changes: 17 additions & 0 deletions pkg/gen/resource_utils.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package gen

import (
"regexp"
"strings"

"github.com/stripe/stripe-cli/pkg/spec"
Expand Down Expand Up @@ -50,6 +51,22 @@ func FirstSentence(s string) string {
return s
}

// mdLinkRe matches Markdown links like [text](url) and captures the text.
var mdLinkRe = regexp.MustCompile(`\[([^\]]+)\]\([^)]+\)`)

// CleanDescription prepares a description string for use as a CLI Short field:
// collapses internal newlines to spaces, strips Markdown links (keeping text),
// and removes backticks.
func CleanDescription(s string) string {
s = strings.ReplaceAll(s, "\n", " ")
s = mdLinkRe.ReplaceAllString(s, "$1")
s = strings.ReplaceAll(s, "`", "")
for strings.Contains(s, " ") {
s = strings.ReplaceAll(s, " ", " ")
}
return strings.TrimSpace(s)
}

// ResolveObjectSchema returns s if it is a plain object schema (type "object" or has
// Properties), or the first anyOf/oneOf branch that is an object schema. Returns nil if
// no object branch is found.
Expand Down
4 changes: 2 additions & 2 deletions pkg/gen/resources_cmds.go.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ func add{{ $apiNamespace | ToCamel }}ResourcesCmds(rootCmd *cobra.Command, cfg *
ns{{ $nsName | ToCamel }}Cmd := resource.NewNamespaceCmd(rootCmd, "{{ $nsName }}"){{ end }}{{ end }}{{ end }}

// Resource commands{{ range $nsName, $nsData := $vData.Namespaces }}{{ range $resName, $resData := $nsData.Resources }}{{ if eq $resData.SubResources nil }}
r{{ (printf "%s_%s" $nsName $resName) | ToCamel }}Cmd := resource.NewResourceCmd({{ if ne $nsName "" }}ns{{ $nsName | ToCamel }}Cmd.Cmd{{ else }}rootCmd{{ end }}, "{{ $resName }}"){{ else }}
r{{ (printf "%s_%s" $nsName $resName) | ToCamel }}Cmd := resource.NewResourceCmd({{ if ne $nsName "" }}ns{{ $nsName | ToCamel }}Cmd.Cmd{{ else }}rootCmd{{ end }}, "{{ $resName }}"){{ range $subResName, $subResData := $resData.SubResources }}{{ if $subResData.Operations }}
r{{ (printf "%s_%s" $nsName $resName) | ToCamel }}Cmd := resource.NewResourceCmd({{ if ne $nsName "" }}ns{{ $nsName | ToCamel }}Cmd.Cmd{{ else }}rootCmd{{ end }}, "{{ $resName }}"{{ if $resData.Description }}, {{ $resData.Description | quote }}{{ end }}){{ else }}
r{{ (printf "%s_%s" $nsName $resName) | ToCamel }}Cmd := resource.NewResourceCmd({{ if ne $nsName "" }}ns{{ $nsName | ToCamel }}Cmd.Cmd{{ else }}rootCmd{{ end }}, "{{ $resName }}"{{ if $resData.Description }}, {{ $resData.Description | quote }}{{ end }}){{ range $subResName, $subResData := $resData.SubResources }}{{ if $subResData.Operations }}
r{{ (printf "%s_%s_%s" $nsName $resName $subResName) | ToCamel }}Cmd := resource.NewResourceCmd(r{{ (printf "%s_%s" $nsName $resName) | ToCamel }}Cmd.Cmd, "{{ $subResName }}"){{ end }}{{ end }}{{ end }}{{ end }}{{ end }}

// Operation commands{{ range $nsName, $nsData := $vData.Namespaces }}{{ range $resName, $resData := $nsData.Resources }}{{ range $opName, $opData := $resData.Operations }}
Expand Down
Loading