Document required fields (#198)

Closes: #167

Author: karencfv

internal/generate/paths.go

@@ -141,7 +141,7 @@ func buildMethod(f *os.File, spec *openapi3.T, method string, path string, o *op
 	}
 
 	methodName := strcase.ToCamel(o.OperationID)
-	pInfo := buildParams(o, method, methodName)
+	pInfo := buildParams(o, methodName)
 
 	// Adapt for ListAll methods
 	if isGetAllPages && len(pagedRespType) > 0 {
@@ -348,7 +348,7 @@ func buildPathOrQueryParams(paramType string, params map[string]*openapi3.Parame
 	return pathParams, nil
 }
 
-func buildParams(operation *openapi3.Operation, method, opID string) paramsInfo {
+func buildParams(operation *openapi3.Operation, opID string) paramsInfo {
 	pInfo := paramsInfo{
 		parameters: make(map[string]*openapi3.Parameter, 0),
 	}

internal/generate/types.go

@@ -100,12 +100,32 @@ func constructParamTypes(paths map[string]*openapi3.PathItem) []TypeTemplate {
 		sort.Strings(keys)
 		for _, op := range keys {
 			o := ops[op]
+			requiredFields := ""
+
+			// Some required fields are defined in vendor extensions
+			for k, v := range o.Extensions {
+				if k == "x-dropshot-pagination" {
+					for i, j := range v.(map[string]interface{}) {
+						if i == "required" {
+							values, ok := j.([]interface{})
+							if ok {
+								for _, field := range values {
+									str, ok := field.(string)
+									if ok {
+										requiredFields = requiredFields + fmt.Sprintf("\n// - %v", strcase.ToCamel(str))
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+
 			if len(o.Parameters) > 0 || o.RequestBody != nil {
 				paramsTypeName := strcase.ToCamel(o.OperationID) + "Params"
 				paramsTpl := TypeTemplate{
-					Type:        "struct",
-					Name:        paramsTypeName,
-					Description: "// " + paramsTypeName + " is the request parameters for " + strcase.ToCamel(o.OperationID),
+					Type: "struct",
+					Name: paramsTypeName,
 				}
 
 				fields := make([]TypeFields, 0)
@@ -121,6 +141,10 @@ func constructParamTypes(paths map[string]*openapi3.PathItem) []TypeTemplate {
 						Type: convertToValidGoType("", p.Value.Schema),
 					}
 
+					if p.Value.Required {
+						requiredFields = requiredFields + fmt.Sprintf("\n// - %s", paramName)
+					}
+
 					serInfo := fmt.Sprintf("`json:\"%s,omitempty\" yaml:\"%s,omitempty\"`", p.Value.Name, p.Value.Name)
 					field.SerializationInfo = serInfo
 
@@ -147,9 +171,18 @@ func constructParamTypes(paths map[string]*openapi3.PathItem) []TypeTemplate {
 							SerializationInfo: "`json:\"body,omitempty\" yaml:\"body,omitempty\"`",
 						}
 					}
+					// Body is always a required field
+					requiredFields = requiredFields + "\n// - Body"
 					fields = append(fields, field)
 				}
 				paramsTpl.Fields = fields
+
+				description := "// " + paramsTypeName + " is the request parameters for " +
+					strcase.ToCamel(o.OperationID)
+				if requiredFields != "" {
+					description = description + "\n//\n// Required fields:" + requiredFields
+				}
+				paramsTpl.Description = description
 				paramTypes = append(paramTypes, paramsTpl)
 			}
 		}
@@ -400,7 +433,7 @@ func populateTypeTemplates(name string, s *openapi3.Schema, enumFieldName string
 		typeTpl.Type = fmt.Sprintf("[]%s", s.Items.Value.Type)
 		typeTpl.Name = typeName
 	case "object":
-		typeTpl = createTypeObject(s.Properties, name, typeName, formatTypeDescription(typeName, s))
+		typeTpl = createTypeObject(s, name, typeName, formatTypeDescription(typeName, s))
 
 		// Iterate over the properties and append the types, if we need to.
 		for k, v := range s.Properties {
@@ -439,7 +472,7 @@ func populateTypeTemplates(name string, s *openapi3.Schema, enumFieldName string
 	return types, enumTypes
 }
 
-func createTypeObject(schemas map[string]*openapi3.SchemaRef, name, typeName, description string) TypeTemplate {
+func createTypeObject(schema *openapi3.Schema, name, typeName, description string) TypeTemplate {
 	// TODO: Create types out of the schemas instead of plucking them out of the objects
 	// will leave this for another PR, because the yak shaving is getting ridiculous.
 	// Tracked -> https://github.com/oxidecomputer/oxide.go/issues/110
@@ -450,11 +483,11 @@ func createTypeObject(schemas map[string]*openapi3.SchemaRef, name, typeName, de
 	}
 
 	typeTpl := TypeTemplate{
-		Description: description,
-		Name:        typeName,
-		Type:        "struct",
+		Name: typeName,
+		Type: "struct",
 	}
 
+	schemas := schema.Properties
 	// We want to ensure we keep the order
 	keys := make([]string, 0)
 	for k := range schemas {
@@ -496,6 +529,14 @@ func createTypeObject(schemas map[string]*openapi3.SchemaRef, name, typeName, de
 	}
 	typeTpl.Fields = fields
 
+	if len(schema.Required) > 0 {
+		description = description + "\n//\n// Required fields:"
+		for _, r := range schema.Required {
+			description = description + fmt.Sprintf("\n// - %s", strcase.ToCamel(r))
+		}
+	}
+	typeTpl.Description = description
+
 	return typeTpl
 }
 

internal/generate/types_test.go

@@ -103,17 +103,19 @@ func Test_generateTypes(t *testing.T) {
 }
 
 func Test_createTypeObject(t *testing.T) {
-	typesSpec := map[string]*openapi3.SchemaRef{
-		"snapshot_id": {
-			Value: &openapi3.Schema{Type: "string", Format: "uuid"},
-		},
-		"type": {
-			Value: &openapi3.Schema{Type: "string", Enum: []interface{}{"snapshot"}},
-		},
-	}
+	typesSpec := openapi3.Schema{
+		Required: []string{"type"},
+		Properties: map[string]*openapi3.SchemaRef{
+			"snapshot_id": {
+				Value: &openapi3.Schema{Type: "string", Format: "uuid"},
+			},
+			"type": {
+				Value: &openapi3.Schema{Type: "string", Enum: []interface{}{"snapshot"}},
+			},
+		}}
 
 	type args struct {
-		s        map[string]*openapi3.SchemaRef
+		s        openapi3.Schema
 		name     string
 		typeName string
 	}
@@ -126,7 +128,7 @@ func Test_createTypeObject(t *testing.T) {
 			name: "success",
 			args: args{typesSpec, "DiskSource", "DiskSourceSnapshot"},
 			want: TypeTemplate{
-				Description: "Create a disk from a disk snapshot",
+				Description: "Create a disk from a disk snapshot\n//\n// Required fields:\n// - Type",
 				Name:        "DiskSourceSnapshot",
 				Type:        "struct", Fields: []TypeFields{
 					{
@@ -147,7 +149,7 @@ func Test_createTypeObject(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := createTypeObject(tt.args.s, tt.args.name, tt.args.typeName, "Create a disk from a disk snapshot")
+			got := createTypeObject(&tt.args.s, tt.args.name, tt.args.typeName, "Create a disk from a disk snapshot")
 			assert.Equal(t, tt.want, got)
 		})
 	}
@@ -245,7 +247,10 @@ func Test_createOneOf(t *testing.T) {
 					Description: "// ImageSourceType is the type definition for a ImageSourceType.", Name: "ImageSourceType", Type: "string",
 				},
 				{
-					Description: "// ImageSourceUrl is the type definition for a ImageSourceUrl.", Name: "ImageSourceUrl", Type: "struct", Fields: []TypeFields{
+					Description: "// ImageSourceUrl is the type definition for a ImageSourceUrl.\n//\n// Required fields:\n// - Type\n// - Url",
+					Name:        "ImageSourceUrl",
+					Type:        "struct",
+					Fields: []TypeFields{
 						{
 							Description: "", Name: "Type", Type: "ImageSourceType", SerializationInfo: "`json:\"type,omitempty\" yaml:\"type,omitempty\"`",
 						},
@@ -255,7 +260,10 @@ func Test_createOneOf(t *testing.T) {
 					},
 				},
 				{
-					Description: "// ImageSourceSnapshot is the type definition for a ImageSourceSnapshot.", Name: "ImageSourceSnapshot", Type: "struct", Fields: []TypeFields{
+					Description: "// ImageSourceSnapshot is the type definition for a ImageSourceSnapshot.\n//\n// Required fields:\n// - Id\n// - Type",
+					Name:        "ImageSourceSnapshot",
+					Type:        "struct",
+					Fields: []TypeFields{
 						{
 							Description: "", Name: "Id", Type: "string", SerializationInfo: "`json:\"id,omitempty\" yaml:\"id,omitempty\"`",
 						},