Update comments

hashicorp · Mar 28, 2019 · e5e299c · e5e299c
1 parent 17320e3
commit e5e299c
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 16 deletions.
diff --git a/logical/framework/backend.go b/logical/framework/backend.go
@@ -506,8 +506,11 @@ type FieldSchema struct {
 	Required    bool
 	Deprecated  bool
 
-	// Query indicates this field will be sent as a query parameter. It doesn't
-	// affect handling of the value, but may be used for documentation.
+	// Query indicates this field will be sent as a query parameter:
+	//
+	//   /v1/foo/bar?some_param=some_value
+	//
+	// It doesn't affect handling of the value, but may be used for documentation.
 	Query bool
 
 	// AllowedValues is an optional list of permitted values for this field.

diff --git a/logical/framework/openapi.go b/logical/framework/openapi.go
@@ -148,20 +148,24 @@ type OASMediaTypeObject struct {
 }
 
 type OASSchema struct {
-	Type             string                `json:"type,omitempty"`
-	Description      string                `json:"description,omitempty"`
-	Properties       map[string]*OASSchema `json:"properties,omitempty"`
-	Items            *OASSchema            `json:"items,omitempty"`
-	Format           string                `json:"format,omitempty"`
-	Pattern          string                `json:"pattern,omitempty"`
-	Enum             []interface{}         `json:"enum,omitempty"`
-	Default          interface{}           `json:"default,omitempty"`
-	Example          interface{}           `json:"example,omitempty"`
-	Deprecated       bool                  `json:"deprecated,omitempty"`
-	Required         []string              `json:"required,omitempty"`
-	DisplayName      string                `json:"x-vault-displayName,omitempty" mapstructure:"x-vault-displayName,omitempty"`
-	DisplayValue     interface{}           `json:"x-vault-displayValue,omitempty" mapstructure:"x-vault-displayValue,omitempty"`
-	DisplaySensitive bool                  `json:"x-vault-displaySensitive,omitempty" mapstructure:"x-vault-displaySensitive,omitempty"`
+	Type        string                `json:"type,omitempty"`
+	Description string                `json:"description,omitempty"`
+	Properties  map[string]*OASSchema `json:"properties,omitempty"`
+
+	// Required is a list of keys in Properties that are required to be present. This is a different
+	// approach than OASParameter (unfortunately), but is how JSONSchema handles 'required'.
+	Required []string `json:"required,omitempty"`
+
+	Items            *OASSchema    `json:"items,omitempty"`
+	Format           string        `json:"format,omitempty"`
+	Pattern          string        `json:"pattern,omitempty"`
+	Enum             []interface{} `json:"enum,omitempty"`
+	Default          interface{}   `json:"default,omitempty"`
+	Example          interface{}   `json:"example,omitempty"`
+	Deprecated       bool          `json:"deprecated,omitempty"`
+	DisplayName      string        `json:"x-vault-displayName,omitempty" mapstructure:"x-vault-displayName,omitempty"`
+	DisplayValue     interface{}   `json:"x-vault-displayValue,omitempty" mapstructure:"x-vault-displayValue,omitempty"`
+	DisplaySensitive bool          `json:"x-vault-displaySensitive,omitempty" mapstructure:"x-vault-displaySensitive,omitempty"`
 }
 
 type OASResponse struct {