fix(description): use descriptions from schema

Using descriptions from the oas schema if available,
which are generally more descriptive.

Author: toumorokoshi

go.mod

@@ -17,3 +17,6 @@ require (
 	golang.org/x/text v0.19.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
+
+// uncomment for local development.
+// replace github.com/aep-dev/aep-lib-go => ../aep-lib-go

internal/service/resource_definition.go

@@ -202,41 +202,45 @@ func ExecuteResourceCommand(r *api.Resource, args []string) (*http.Request, stri
 
 func addSchemaFlags(c *cobra.Command, schema openapi.Schema, args map[string]interface{}) error {
 	for name, prop := range schema.Properties {
+		description := prop.Description
+		if description == "" {
+			description = fmt.Sprintf("The %v of the resource", name)
+		}
 		if prop.ReadOnly {
 			continue
 		}
 		switch prop.Type {
 		case "string":
 			var value string
 			args[name] = &value
-			c.Flags().StringVar(&value, name, "", fmt.Sprintf("The %v of the resource", name))
+			c.Flags().StringVar(&value, name, "", description)
 		case "integer":
 			var value int
 			args[name] = &value
-			c.Flags().IntVar(&value, name, 0, fmt.Sprintf("The %v of the resource", name))
+			c.Flags().IntVar(&value, name, 0, description)
 		case "number":
 			var value float64
 			args[name] = &value
-			c.Flags().Float64Var(&value, name, 0, fmt.Sprintf("The %v of the resource", name))
+			c.Flags().Float64Var(&value, name, 0, description)
 		case "boolean":
 			var value bool
 			args[name] = &value
-			c.Flags().BoolVar(&value, name, false, fmt.Sprintf("The %v of the resource", name))
+			c.Flags().BoolVar(&value, name, false, description)
 		case "array":
 			if prop.Items == nil {
 				return fmt.Errorf("items is required for array type, not found for field %v", name)
 			}
 			var value []interface{}
 			args[name] = &value
-			c.Flags().Var(&ArrayFlag{&value, prop.Items.Type}, name, fmt.Sprintf("The %v of the resource", name))
+			c.Flags().Var(&ArrayFlag{&value, prop.Items.Type}, name, description)
 		case "object":
 			var parsedValue map[string]interface{}
 			args[name] = &parsedValue
-			c.Flags().Var(&JSONFlag{&parsedValue}, name, fmt.Sprintf("The %v of the resource", name))
+			c.Flags().Var(&JSONFlag{&parsedValue}, name, description)
 		default:
 			var parsedValue map[string]interface{}
 			args[name] = &parsedValue
-			c.Flags().Var(&JSONFlag{&parsedValue}, name, fmt.Sprintf("The %v of the resource", name))
+			c.Flags().Var(&JSONFlag{&parsedValue}, name, description)
 		}
 	}
 	for _, f := range schema.Required {

internal/service/resource_definition_test.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/aep-dev/aep-lib-go/pkg/api"
@@ -19,7 +20,8 @@ func getTestAPI() *api.API {
 		Schema: &openapi.Schema{
 			Properties: map[string]openapi.Schema{
 				"name": {
-					Type: "string",
+					Type:        "string",
+					Description: "The name of the project",
 				},
 				"description": {
 					Type: "string",
@@ -118,12 +120,49 @@ func getTestAPI() *api.API {
 				Parents:  []string{},
 				Schema:   &openapi.Schema{},
 			},
+			"shelf": {
+				Singular: "shelf",
+				Plural:   "shelves",
+				Parents:  []string{"project"},
+				Schema:   &openapi.Schema{},
+			},
+			"book": {
+				Singular: "book",
+				Plural:   "books",
+				Parents:  []string{"shelf"},
+				Schema: &openapi.Schema{
+					Properties: map[string]openapi.Schema{
+						"title": {
+							Type: "string",
+						},
+						"author": {
+							Type: "string",
+						},
+						"path": {
+							Type:     "string",
+							ReadOnly: true,
+						},
+					},
+				},
+				Methods: api.Methods{
+					Create: &api.CreateMethod{
+						SupportsUserSettableCreate: true,
+					},
+				},
+			},
 		},
 	}
 	err := api.AddImplicitFieldsAndValidate(a)
 	if err != nil {
 		panic(err)
 	}
+	// Restore ReadOnly for book path, as AddImplicitFieldsAndValidate overwrites it
+	if book, ok := a.Resources["book"]; ok {
+		if pathProp, ok := book.Schema.Properties["path"]; ok {
+			pathProp.ReadOnly = true
+			book.Schema.Properties["path"] = pathProp
+		}
+	}
 	return a
 }
 
@@ -135,8 +174,10 @@ func TestExecuteCommand(t *testing.T) {
 		expectedQuery  string
 		expectedPath   string
 		expectedMethod string
+
 		wantErr        bool
 		body           string
+		expectedOutput string
 	}{
 		{
 			name:           "simple resource no parents",
@@ -240,20 +281,43 @@ func TestExecuteCommand(t *testing.T) {
 			wantErr:        false,
 			body:           `{"description":"Manual dataset","name":"manual-dataset"}`,
 		},
+		{
+			name:           "create book with read-only path flag",
+			resource:       "book",
+			args:           []string{"--project=myproject", "--shelf=myshelf", "create", "mybook", "--path=some/path"},
+			expectedPath:   "",
+			expectedMethod: "",
+			wantErr:        true,
+			body:           "",
+		},
+		{
+			name:           "help with description",
+			resource:       "project",
+			args:           []string{"create", "--help"},
+			expectedPath:   "",
+			expectedMethod: "",
+			wantErr:        false,
+			expectedOutput: "The name of the project",
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			a := getTestAPI()
-			req, _, err := ExecuteResourceCommand(a.Resources[tt.resource], tt.args)
+			req, output, err := ExecuteResourceCommand(a.Resources[tt.resource], tt.args)
 			if (err != nil) != tt.wantErr {
 				t.Errorf("ExecuteCommand() error = %v, wantErr %v", err, tt.wantErr)
 				return
 			}
-			if !tt.wantErr && req == nil {
+			if !tt.wantErr && req == nil && tt.expectedOutput == "" {
 				t.Error("ExecuteCommand() returned nil request when no error expected")
 			}
-			if !tt.wantErr {
+			if tt.expectedOutput != "" {
+				if !strings.Contains(output, tt.expectedOutput) {
+					t.Errorf("ExecuteCommand() output = %q, want to contain %q", output, tt.expectedOutput)
+				}
+			}
+			if !tt.wantErr && req != nil {
 				// Verify the request path matches expected pattern
 				if req.URL.Path != tt.expectedPath {
 					t.Errorf("ExecuteCommand() request path = %v, want %v", req.URL.Path, tt.expectedPath)

internal/service/service_test.go

@@ -22,12 +22,12 @@ func TestService_ExecuteCommand_ListResources(t *testing.T) {
 		{
 			name:     "no arguments",
 			args:     []string{},
-			expected: "Available resources:\n  - comment\n  - dataset\n  - project\n  - user\n",
+			expected: "Available resources:\n  - book\n  - comment\n  - dataset\n  - project\n  - shelf\n  - user\n",
 		},
 		{
 			name:     "help flag",
 			args:     []string{"--help"},
-			expected: "Available resources:\n  - comment\n  - dataset\n  - project\n  - user\n",
+			expected: "Available resources:\n  - book\n  - comment\n  - dataset\n  - project\n  - shelf\n  - user\n",
 		},
 		{
 			name:          "unknown resource",