v2 improves params documentation

modules/openapi-json-schema-generator/src/main/java/org/openapijsonschematools/codegen/model/CodegenOperation.java

@@ -80,6 +80,42 @@ public CodegenOperation(Boolean deprecated, boolean hasErrorResponseObject, Stri
         this.jsonPathPiece = jsonPathPiece;
     }
 
+    // used by operation templates
+    public Map<String, CodegenResponse> getNonErrorResponses() {
+        HashMap<String,CodegenResponse> nonErrorResponses = new HashMap<>();
+        if (statusCodeResponses != null) {
+            for (Map.Entry<Integer, CodegenResponse> entry: statusCodeResponses.entrySet()) {
+                if (entry.getKey() >= 200 && entry.getKey() <= 299) {
+                    nonErrorResponses.put(entry.getKey().toString(), entry.getValue());
+                }
+            }
+        }
+        if (wildcardCodeResponses != null) {
+            for (Map.Entry<Integer, CodegenResponse> entry: wildcardCodeResponses.entrySet()) {
+                if (entry.getKey() == 2) {
+                    nonErrorResponses.put(entry.getKey().toString(), entry.getValue());
+                }
+            }
+        }
+        if (defaultResponse != null) {
+            if (nonErrorResponses.isEmpty()) {
+                /* default response should be non-error because
+                The Responses Object MUST contain at least one response code, and if only one response code
+                is provided it SHOULD be the response for a successful operation call.
+                 */
+                nonErrorResponses.put("default", defaultResponse);
+            } else {
+                // the code does not know if this is an error response or non-error
+                // TODO add generation option that specifies it?
+                nonErrorResponses.put("default", defaultResponse);
+            }
+        }
+        if (nonErrorResponses.isEmpty()) {
+            return null;
+        }
+        return nonErrorResponses;
+    }
+
     public boolean getAllResponsesAreErrors() {
         if (responses.size() == 1 && defaultResponse != null) {
             return false;

modules/openapi-json-schema-generator/src/main/java/org/openapijsonschematools/codegen/model/CodegenRequestBody.java

@@ -1,8 +1,11 @@
 package org.openapijsonschematools.codegen.model;
 
+import java.util.HashSet;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Set;
 import java.util.TreeSet;
 
 /**
@@ -21,6 +24,49 @@ public class CodegenRequestBody {
     public final CodegenKey jsonPathPiece;
     public final CodegenRefInfo<CodegenRequestBody> refInfo;
 
+    /*
+    A method that returns all content schemas
+    This only works on the RequestBody that contains a CodegenMediaType with a schema definition
+     */
+    public Set<CodegenSchema> getContentSchemas() {
+        if (content == null) {
+            return null;
+        }
+        LinkedHashSet<CodegenSchema> schemas = new LinkedHashSet<>();
+        LinkedHashSet<CodegenSchema> anyTypeSchemas = new LinkedHashSet<>();
+        for (CodegenMediaType mediaType: content.values()) {
+            if (mediaType == null) {
+                continue;
+            }
+            if (mediaType.schema == null) {
+                continue;
+            }
+            CodegenSchema schema = new CodegenSchema();
+            if (mediaType.schema.refInfo != null) {
+                // TODO adjust this for 3.1.0
+                // in 3.1.0 ref can be combined with other constraints
+                // so types and format should come from
+                // the first schema then, not the deepest ref
+                CodegenSchema deepest = mediaType.schema.getDeepestRef();
+                schema.types = deepest.types;
+                schema.format = deepest.format;
+            } else {
+                schema.types = mediaType.schema.types;
+                schema.format = mediaType.schema.format;
+            }
+            if (schema.types == null && schema.format == null) {
+                // return only anyType if it exists because it covers all use cases
+                anyTypeSchemas.add(schema);
+                return anyTypeSchemas;
+            }
+            schemas.add(schema);
+        }
+        if (schemas.isEmpty()) {
+            return null;
+        }
+        return schemas;
+    }
+
     public CodegenRequestBody(String description, String unescapedDescription, Map<String, Object> vendorExtensions, Boolean required, LinkedHashMap<CodegenKey, CodegenMediaType> content, TreeSet<String> imports, String componentModule, CodegenKey jsonPathPiece, CodegenRefInfo<CodegenRequestBody> refInfo) {
         this.description = description;
         this.unescapedDescription = unescapedDescription;

modules/openapi-json-schema-generator/src/main/java/org/openapijsonschematools/codegen/templating/handlebars/CustomHelpers.java

@@ -86,37 +86,4 @@ public Object apply(final Object context, final Options options) {
             return null;
         }
     },
-
-    /**
-     * gets the anchor identifier suffix
-     *
-     */
-    getIdentifierSuffix {
-        @Override
-        public Object apply(final Object context, final Options options) {
-            Object b = options.param(0, null);
-            if (context instanceof HashMap && b instanceof List) {
-                HashMap<List<String>, Integer> thisContext = (HashMap<List<String>, Integer>) context;
-                List<String> identifier = getIdentifier((List<?>) b);
-                int newQty = thisContext.getOrDefault(identifier, -1) + 1;
-                ((HashMap<List<String>, Integer>) context).put(identifier, newQty);
-                if (newQty == 0) {
-                    return "";
-                }
-                return "-"+ newQty;
-            }
-            return null;
-        }
-    };
-    private static List<String> getIdentifier(List<?> identifierPieces) {
-        ArrayList<String> result = new ArrayList<>();
-        for (Object item: identifierPieces) {
-            if (item instanceof CodegenKey) {
-                result.add(((CodegenKey) item).anchorPiece);
-            } else if (item instanceof String) {
-                result.add((String) item);
-            }
-        }
-        return Collections.unmodifiableList(result);
-    }
 }

modules/openapi-json-schema-generator/src/main/resources/python/_helper_schema_python_types.hbs

@@ -1 +1 @@
-{{#eq types null}}dict, frozendict.frozendict, str, datetime.date, datetime.datetime, uuid.UUID, int, float, decimal.Decimal, bool, None, list, tuple, bytes, io.FileIO, io.BufferedReader, {{else}}{{#each types}}{{#eq this "array"}}list, tuple, {{/eq}}{{#eq this "object"}}dict, frozendict.frozendict, {{/eq}}{{#eq this "null"}}None, {{/eq}}{{#eq this "string" }}{{#neq ../format "binary"}}str, {{/neq}}{{#eq ../format "date"}}datetime.date, {{/eq}}{{#eq ../format "date-time"}}datetime.datetime, {{/eq}}{{#eq ../format "uuid"}}uuid.UUID, {{/eq}}{{#eq ../format "binary"}}bytes, io.FileIO, io.BufferedReader, {{/eq}}{{/eq}}{{#eq this "integer"}}decimal.Decimal, int, {{/eq}}{{#eq this "number"}}decimal.Decimal, int, float, {{/eq}}{{#eq this "boolean"}}bool, {{/eq}}{{/each}}{{/eq}}
+{{#eq types null}}dict, frozendict.frozendict, str, datetime.date, datetime.datetime, uuid.UUID, int, float, decimal.Decimal, bool, None, list, tuple, bytes, io.FileIO, io.BufferedReader{{else}}{{#each types}}{{#unless @first}}, {{/unless}}{{#eq this "array"}}list, tuple{{/eq}}{{#eq this "object"}}dict, frozendict.frozendict{{/eq}}{{#eq this "null"}}None{{/eq}}{{#eq this "string" }}{{#neq ../format "binary"}}str{{/neq}}{{#eq ../format "date"}}, datetime.date{{/eq}}{{#eq ../format "date-time"}}, datetime.datetime{{/eq}}{{#eq ../format "uuid"}}, uuid.UUID{{/eq}}{{#eq ../format "binary"}}bytes, io.FileIO, io.BufferedReader{{/eq}}{{/eq}}{{#eq this "integer"}}decimal.Decimal, int{{/eq}}{{#eq this "number"}}decimal.Decimal, int, float{{/eq}}{{#eq this "boolean"}}bool{{/eq}}{{/each}}{{/eq}}

modules/openapi-json-schema-generator/src/main/resources/python/_helper_schema_python_types_newline.hbs

@@ -0,0 +1,72 @@
+{{#eq types null}}
+dict,
+frozendict.frozendict,
+str,
+datetime.date,
+datetime.datetime,
+uuid.UUID,
+int,
+float,
+decimal.Decimal,
+bool,
+None,
+list,
+tuple,
+bytes,
+io.FileIO,
+io.BufferedReader
+{{else}}
+    {{#each types}}
+        {{#eq this "array"}}
+list,
+tuple{{#unless @last}},{{/unless}}
+        {{/eq}}
+        {{#eq this "object"}}
+dict,
+frozendict.frozendict{{#unless @last}},{{/unless}}
+        {{/eq}}
+        {{#eq this "null"}}
+None{{#unless @last}},{{/unless}}
+        {{/eq}}
+        {{#eq this "string" }}
+            {{#eq ../format null}}
+str{{#unless @last}},{{/unless}}
+            {{else}}
+                {{#eq ../format "date"}}
+str,
+datetime.date{{#unless @last}},{{/unless}}
+                {{else}}
+                    {{#eq ../format "date-time"}}
+str,
+datetime.datetime{{#unless @last}},{{/unless}}
+                    {{else}}
+                        {{#eq ../format "uuid"}}
+str,
+uuid.UUID{{#unless @last}},{{/unless}}
+                        {{else}}
+                            {{#eq ../format "binary"}}
+bytes,
+io.FileIO,
+io.BufferedReader{{#unless @last}},{{/unless}}
+                            {{else}}
+str{{#unless @last}},{{/unless}}
+                            {{/eq}}
+                        {{/eq}}
+                    {{/eq}}
+                {{/eq}}
+            {{/eq}}
+        {{/eq}}
+        {{#eq this "integer"}}
+decimal.Decimal,
+int{{#unless @last}},{{/unless}}
+        {{/eq}}
+        {{#eq this "number"}}
+decimal.Decimal,
+int,
+float{{#unless @last}},{{/unless}}
+        {{/eq}}
+        {{#eq this "boolean"}}
+bool{{#unless @last}},{{/unless}}
+        {{/eq}}
+    {{/each}}
+{{/eq}}

modules/openapi-json-schema-generator/src/main/resources/python/components/_helper_anchor_id.hbs

@@ -1 +1 @@
-{{#each identifierPieces}}{{#if this.anchorPiece}}{{this.anchorPiece}}{{else}}{{this}}{{/if}}{{#unless @last}}-{{/unless}}{{/each}}{{#if includeSuffix}}{{> components/schemas/_helper_identifier_suffix identifierSuffix=(getIdentifierSuffix identifierToHeadingQty identifierPieces) }}{{/if}}
+{{#each identifierPieces}}{{#if this.anchorPiece}}{{this.anchorPiece}}{{else}}{{this}}{{/if}}{{#unless @last}}-{{/unless}}{{/each}}

modules/openapi-json-schema-generator/src/main/resources/python/components/_helper_header_from_identifier_pieces.hbs

@@ -1,4 +1 @@
 {{headerSize}} {{#each identifierPieces}}{{#if this.camelCase}}{{this.camelCase}}{{else}}{{this}}{{/if}}{{#unless @last}} {{/unless}}{{/each}}
-{{#if recordUsage}}
-{{> components/schemas/_helper_identifier_suffix identifierSuffix=(getIdentifierSuffix identifierToHeadingQty identifierPieces) }}
-{{/if}}

modules/openapi-json-schema-generator/src/main/resources/python/components/_helper_schema_accessed_types.hbs

@@ -1 +1 @@
-{{#eq types null}}frozendict.frozendict, str, decimal.Decimal, BoolClass, NoneClass, tuple, bytes, io.FileIO, {{else}}{{#each types}}{{#eq this "array"}}tuple, {{/eq}}{{#eq this "object"}}frozendict.frozendict, {{/eq}}{{#eq this "null"}}NoneClass, {{/eq}}{{#eq this "string" }}{{#neq ../format "binary"}}str, {{/neq}}{{#eq ../format "binary"}}bytes, io.FileIO, {{/eq}}{{/eq}}{{#eq this "integer"}}decimal.Decimal, {{/eq}}{{#eq this "number"}}decimal.Decimal, {{/eq}}{{#eq this "boolean"}}BoolClass, {{/eq}}{{/each}}{{/eq}}
+{{#eq types null}}frozendict.frozendict, str, decimal.Decimal, BoolClass, NoneClass, tuple, bytes, io.FileIO{{else}}{{#each types}}{{#unless @first}}, {{/unless}}{{#eq this "array"}}tuple{{/eq}}{{#eq this "object"}}frozendict.frozendict{{/eq}}{{#eq this "null"}}NoneClass{{/eq}}{{#eq this "string" }}{{#neq ../format "binary"}}str{{/neq}}{{#eq ../format "binary"}}bytes, io.FileIO{{/eq}}{{/eq}}{{#eq this "integer"}}decimal.Decimal{{/eq}}{{#eq this "number"}}decimal.Decimal{{/eq}}{{#eq this "boolean"}}BoolClass{{/eq}}{{/each}}{{/eq}}

modules/openapi-json-schema-generator/src/main/resources/python/components/headers/header_doc.hbs

@@ -3,9 +3,9 @@
 {{packageName}}.components.headers.{{componentModule}}
     {{/if}}
     {{#eq identifierPieces.size 0}}
-{{> components/_helper_header_from_identifier_pieces identifierPieces=(append identifierPieces "Header" jsonPathPiece) recordUsage=true }}
+{{> components/_helper_header_from_identifier_pieces identifierPieces=(append identifierPieces "Header" jsonPathPiece) }}
     {{else}}
-{{> components/_helper_header_from_identifier_pieces recordUsage=false }}
+{{> components/_helper_header_from_identifier_pieces }}
     {{/eq}}
     {{#if description}}
 
@@ -16,10 +16,10 @@
         {{#with getDeepestRef}}
             {{#if schema}}
                 {{#with schema}}
-{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) jsonPathPiece) recordUsage=false }}
+{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) jsonPathPiece) }}
 Ref Class | Input Type | Accessed Type | Description
 --------- | ---------- | ------------- | ------------
-[{{../../refInfo.refClass}}.schema](../../components/headers/{{../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) jsonPathPiece) includeSuffix=false }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../description}}{{../../description}}{{/if}}
+[{{../../refInfo.refClass}}.schema](../../components/headers/{{../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) jsonPathPiece) }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../description}}{{../../description}}{{/if}}
                 {{/with}}
             {{/if}}
             {{#each content}}
@@ -29,14 +29,14 @@ Ref Class | Input Type | Accessed Type | Description
 Content-Type | Schema
 ------------ | -------
                 {{/if}}
-"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) includeSuffix=false }})
+"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) }})
             {{/each}}
             {{#each content}}
                 {{#with this.schema}}
-{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) recordUsage=false }}
+{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) }}
 Ref Class | Input Type | Accessed Type | Description
 --------- | ---------- | ------------- | ------------
-[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.schema](../../components/headers/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) includeSuffix=false }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../../description}}{{../../../description}}{{/if}}
+[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.schema](../../components/headers/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../../description}}{{../../../description}}{{/if}}
                 {{/with}}
             {{/each}}
         {{/with}}
@@ -54,7 +54,7 @@ Ref Class | Input Type | Accessed Type | Description
 Content-Type | Schema
 ------------ | -------
                 {{/if}}
-"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) includeSuffix=false }})
+"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) }})
             {{/each}}
             {{#each content}}
                 {{#with this}}

modules/openapi-json-schema-generator/src/main/resources/python/components/parameters/parameter_doc.hbs

@@ -3,9 +3,9 @@
 {{../packageName}}.components.parameters.{{componentModule}}
 {{/if}}
 {{#eq identifierPieces.size 0}}
-{{> components/_helper_header_from_identifier_pieces identifierPieces=(append identifierPieces "Parameter" jsonPathPiece) recordUsage=true }}
+{{> components/_helper_header_from_identifier_pieces identifierPieces=(append identifierPieces "Parameter" jsonPathPiece) }}
 {{else}}
-{{> components/_helper_header_from_identifier_pieces recordUsage=false }}
+{{> components/_helper_header_from_identifier_pieces }}
 {{/eq}}
 {{#if description}}
 
@@ -16,10 +16,10 @@
     {{#with getDeepestRef}}
         {{#if schema}}
             {{#with schema}}
-{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) jsonPathPiece) recordUsage=false }}
+{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) jsonPathPiece) }}
 Ref Class | Input Type | Accessed Type | Description
 --------- | ---------- | ------------- | ------------
-[{{../../refInfo.refClass}}.schema](../../components/parameters/{{../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) jsonPathPiece) includeSuffix=false }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../description}}{{../../description}}{{/if}}
+[{{../../refInfo.refClass}}.schema](../../components/parameters/{{../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) jsonPathPiece) }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../description}}{{../../description}}{{/if}}
             {{/with}}
         {{else}}
             {{#each getDeepestRef.content}}
@@ -29,14 +29,14 @@ Ref Class | Input Type | Accessed Type | Description
 Content-Type | Schema
 ------------ | -------
                 {{/if}}
-"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) includeSuffix=false }})
+"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) }})
             {{/each}}
             {{#each getDeepestRef.content}}
                 {{#with this.schema}}
-{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) recordUsage=false }}
+{{> components/_helper_header_from_identifier_pieces headerSize=(join headerSize "#" "") identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) }}
 Ref Class | Input Type | Accessed Type | Description
 --------- | ---------- | ------------- | ------------
-[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.schema](../../components/parameters/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) includeSuffix=false }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../../description}}{{../../../description}}{{/if}}
+[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.schema](../../components/parameters/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append (newArray ) "content" ../@key jsonPathPiece) }}) | {{> _helper_schema_python_types }} | {{> components/_helper_schema_accessed_types }} | {{#if ../../../description}}{{../../../description}}{{/if}}
                 {{/with}}
             {{/each}}
         {{/if}}
@@ -55,7 +55,7 @@ Ref Class | Input Type | Accessed Type | Description
 Content-Type | Schema
 ------------ | -------
             {{/if}}
-"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) includeSuffix=false }})
+"{{@key.original}}" | [content.{{@key.snakeCase}}.{{this.schema.jsonPathPiece.camelCase}}](#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" @key this.schema.jsonPathPiece) }})
         {{/each}}
         {{#each content}}
             {{#with this.schema}}