improve api, comments and readme

Author: sam-heilbron

README.md

@@ -66,4 +66,10 @@ Other supported options are:
 *   `use_ref`
     *   when set to `true`, the output uses the `$ref` field in OpenAPI spec to reference other schemas.
 *   `yaml`
-    *   when set to `true`, the output is in yaml file.
+    *   when set to `true`, the output is in yaml file.
+*   `include_description`
+    *   when set to `true`, the openapi schema will include descriptions, generated from the proto message comment.
+*   `enum_as_int_or_string`
+    *   when set to `true`, the openapi schema will include `x-kubernetes-int-or-string` on enums.
+*   `additional_empty_schemas`
+    *   a `+` separated list of message names (`core.solo.io.Status`), whose generated schema should be an empty object that accepts all values.

main.go

@@ -104,7 +104,7 @@ func generate(request plugin.CodeGeneratorRequest) (*plugin.CodeGeneratorRespons
 			default:
 				return nil, fmt.Errorf("unknown value '%s' for enum_as_int_or_string", v)
 			}
-		} else if k == "empty_schema" {
+		} else if k == "additional_empty_schema" {
 			messagesWithEmptySchema = strings.Split(v, "+")
 		} else {
 			return nil, fmt.Errorf("unknown argument '%s' specified", k)

openapiGenerator.go

@@ -130,6 +130,11 @@ func newOpenAPIGenerator(
 	}
 }
 
+// buildCustomSchemasByMessageName name returns a mapping of message name to a pre-defined openapi schema
+// It includes:
+//	1. `specialSoloTypes`, a set of pre-defined schemas
+//  2. `messagesWithEmptySchema`, a list of messages that are injected at runtime that should contain
+//  and empty schema which accepts and preserves all fields
 func buildCustomSchemasByMessageName(messagesWithEmptySchema []string) map[string]openapi3.Schema {
 	schemasByMessageName := make(map[string]openapi3.Schema)