v2 documentation improvements (#134)

* Adds top link section in endpoint docs, makes reponses h2

* Adds table of contents

* Moves TOC to h2

* Adds and uses headerSize parameter

* Removes anchorContainsPeriod

* Adjusts request body header size when requestbody is refed

* Updates request body header size for non refed request bodies

* Removes header from request body component module

* Moves code sample to bottom, adds h2 section for authorization, adds to toc

* Adds description and summary sections

* Uses headerSize in parameter docs

* Fixes headerSize in parameter_doc.hbs

* Has header docs use headerSize

* Improves indentation in response bodies

* Adjusts paramter schema depths

* Removes deep headerSize passing in paramter_doc

* dedents schema module in component schema docs

* Flows headerSize into schema docs

* Removes discription when there re no arguments

* Removes auth section if there is no auth

* Uses join for parameter schema docs

* Adds header for each parameter

* Removes redundant data addition

* Header indentation updated in components

* Adds body and header sections to response

* Uses headerSize in response_doc

* Fully uses headerSize in response_doc

* Uses camelCase name in headings for headers and content

* Adds response dscriptions to docs

* Uses headerSize in request body doc

* Adds request body description to docs

* Adds descriptions to responses and request bodies

* Fixes links to ref responses

* Adds parameter and header descriptions

* Adds component schema descriptions

* Increases indentation depth in schema docs

* Reduces composed indentation

* Adds indentation

* All sub lists use numbering

* Removes empty lines from indented schema doc template

* Fixes some tables

* Actually indents subschemas

* Indentation level corrected

* Adds new lines back into schema doc indent template

* Uses headerSize.length in schema_doc_indent

* Removes trailing # from headings in indent

* Adds newline bfore oneOf anyOf allOf Nots

* Removes unneeded deeper indentation

* Adds 1 level of depth to request body schema

* Indents request body schema info under header schema class name

* Improves endpoint response indentation

* Fixes request body links in endpoint docs

* Stops indenting schemas, lists them all at the same level

* Inlines all schemas

* Adds indentation under schema

* Removes RequestBody prefix from request body description

* Removes prefixes from response data

* Moves header summary higher, adds header details removes response prefixes

* Removes prefix from response headers when they are inline

* Adds levels to header docs

* Lists responses after response summary to keep header levels at h6 max

* Removes description prefix from header docs

* Updates parameter descriptions

* Simplifies parameter and header docs

* Simplifies response doc

* Simplies request body doc template

* Simplifies schema doc

* Adds schema writing of anchors with ids containing json path info

* Tweaks schema anchors

* Moves anchor above heading

* Fixes property links

* Fixes required an optional schema docs links

* Adds content type to schema request body section

* Adds newArray and add helpers

* Adds identifierPieces to schema rendering

* Uses identifierPieces

* Generates custom anchor

* Adds anchorPiece

* Uses anchorPiece in anchors

* Sample regen

* Removes manual anchor

* Uses _helper_header_from_identifier_pieces

* Adds Items component schema example

* Adds sample schemas with collisions

* Fixes doc colision in schema property docs

* Simplifies schema doc template

* Updates requestBody doc template

* Simplifies request body docs

* Omits self header prefix in schema and request body docs for inline schemas

* Adjusts when suffix is added to links

* passes in needed identifierPieces into response headers

* Updates header docs

* Adds header content type to schema section in docs

* Updates most of codegen response docs

* Changes content to body

* Fixes template warning by passing in includeSuffix

* Parameter docs updated, parameter docs have needed params

* Adds Schema prefix to component schema h1

* Adds Response prefix to response docs

* Adds prefix to other components

* Adds headers prefix for response header docs

* Adds path to operation docs

* Adds path anchor link

* Adds http method to operation docs

* Operation requestbody heading updated

* Removes template setting of var complexTypePrefix

* Fixes rending of required and optional input type and accessed types for dict keys

* Simplifies dict req and optional input type accessed type template

* Fixes template access warning

* Updates response docs to handle no resonse body schema use case

* response body class updated when no content schemas are defined

* Fixes doc links for self reverences

* moved dict property schema link location in docs

* Adds link to additional properties class in schema docs

* Adds example that shows response body links are working

* Samples regen

* Removes unused templates

* params updated

* sample regen

* Fixes locale invocations

Author: spacether

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

@@ -2569,11 +2569,14 @@ protected CodegenKey getOperationId(Operation operation, String path, String htt
                 operationId = String.join(removeOperationIdPrefixDelimiter, Arrays.copyOfRange(components, component_number, components.length));
             }
         }
+        String camelCase = toModelName(operationId);
+        String anchorPiece = camelCase.toLowerCase(Locale.ROOT);
         return new CodegenKey(
                 operationId,
                 isValid(operationId),
                 getOperationIdSnakeCase(operationId),
-                toModelName(operationId)
+                camelCase,
+                anchorPiece
         );
     }
 
@@ -2634,11 +2637,14 @@ public CodegenOperation fromOperation(String path,
         } else {
             usedPath = path;
         }
+        String camelCase = toModelName(path);
+        String anchorPiece = camelCase.toLowerCase(Locale.ROOT);
         CodegenKey pathKey = new CodegenKey(
                 usedPath,
                 false,  // false because paths have lots of invalid characters
                 toPathFilename(path),
-                toModelName(path)
+                camelCase,
+                anchorPiece
         );
         String sourceJsonPath = "#/paths/" + ModelUtils.encodeSlashes(pathKey.original) + "/" + httpMethod;
 
@@ -2809,12 +2815,14 @@ public CodegenOperation fromOperation(String path,
                 }
             }
         }
-
+        String camelCaseMethod = org.openapijsonschematools.codegen.utils.StringUtils.camelize(httpMethod);
+        String anchorPieceMethod = camelCase.toLowerCase(Locale.ROOT);
         CodegenKey httpMethodKey = new CodegenKey(
                 httpMethod,
                 true,
                 org.openapijsonschematools.codegen.utils.StringUtils.underscore(httpMethod),
-                org.openapijsonschematools.codegen.utils.StringUtils.camelize(httpMethod)
+                camelCaseMethod,
+                anchorPieceMethod
         );
 
         // move "required" parameters in front of "optional" parameters
@@ -4522,6 +4530,7 @@ public CodegenKey getKey(String key, String expectedComponentType) {
         boolean isValid = isValid(usedKey);
         String snakeCaseName = null;
         String camelCaseName = null;
+        String anchorPiece = null;
         switch (expectedComponentType) {
             case "schemas":
                 snakeCaseName = toModelFilename(usedKey);
@@ -4544,22 +4553,29 @@ public CodegenKey getKey(String key, String expectedComponentType) {
                 camelCaseName = getCamelCaseResponse(usedKey);
                 break;
         }
+        if (camelCaseName != null) {
+            anchorPiece = camelCaseName.toLowerCase(Locale.ROOT);
+        }
         return new CodegenKey(
                 usedKey,
                 isValid,
                 snakeCaseName,
-                camelCaseName
+                camelCaseName,
+                anchorPiece
         );
     }
 
     public CodegenKey getKey(String key) {
         String usedKey = handleSpecialCharacters(key);
         boolean isValid = isValid(usedKey);
+        String camelCase = toModelName(usedKey);
+        String anchorPiece = camelCase.toLowerCase(Locale.ROOT);
         return new CodegenKey(
                 usedKey,
                 isValid,
                 toModelFilename(usedKey),
-                toModelName(usedKey)
+                camelCase,
+                anchorPiece
         );
     }
 

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

@@ -395,6 +395,7 @@ private void generateModelDocumentation(List<File> files, Map<String, Object> mo
             String docExtension = config.getDocExtension();
             String suffix = docExtension != null ? docExtension : config.modelDocTemplateFiles().get(templateName);
             String filename = config.modelDocFileFolder() + File.separator + config.toModelDocFilename(modelName) + suffix;
+            modelData.put("headerSize", "#");
 
             File written = processTemplateToFile(modelData, templateName, filename, generateModelDocumentation, CodegenConstants.MODEL_DOCS);
             if (written != null) {
@@ -572,16 +573,20 @@ void generatePaths(List<File> files, Map<String, List<CodegenOperation>> operati
 
                     }
                 }
+                // operation docs
                 for (String templateFile: config.pathEndpointDocTemplateFiles()) {
                     for (Map.Entry<String, CodegenTag> entry: co.tags.entrySet()) {
                         CodegenTag tag = entry.getValue();
                         Map<String, Object> endpointInfo = new HashMap<>();
-                        List<CodegenOperation> operation = Arrays.asList(co);
-                        endpointInfo.put("operation", operation);
+                        endpointInfo.put("operation", co);
                         endpointInfo.put("packageName", packageName);
                         endpointInfo.put("apiPackage", config.apiPackage());
                         endpointInfo.put("basePath", basePath);
                         endpointInfo.put("tag", tag);
+                        endpointInfo.put("headerSize", "#");
+                        endpointInfo.put("complexTypePrefix", "../../../components/schema/");
+                        endpointInfo.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+                        endpointInfo.put("identifierToHeadingQty", new HashMap<>());
                         outputFilename = filenameFromRoot(Arrays.asList("docs", config.apiPackage(), "tags", tag.moduleName, co.operationId.snakeCase + ".md"));
                         apiDocFiles.add(Arrays.asList(endpointInfo, templateFile, outputFilename));
                     }
@@ -800,6 +805,9 @@ private TreeMap<String, CodegenResponse> generateResponses(List<File> files) {
                 Map<String, Object> templateData = new HashMap<>();
                 templateData.put("packageName", config.packageName());
                 templateData.put("complexTypePrefix", "../../components/schema/");
+                templateData.put("headerSize", "#");
+                templateData.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+                templateData.put("identifierToHeadingQty", new HashMap<>());
                 templateData.put("response", response);
                 try {
                     File written = processTemplateToFile(templateData, templateName, filename, generateResponseDocumentation, CodegenConstants.REQUEST_BODY_DOCS);
@@ -821,7 +829,6 @@ private void generateRequestBody(List<File> files, CodegenRequestBody requestBod
         Map<String, Object> templateData = new HashMap<>();
         templateData.put("packageName", config.packageName());
         templateData.put("requestBody", requestBody);
-        templateData.put("docRoot", "../../");
         Boolean generateRequestBodies = Boolean.TRUE;
         Map<String, String> templateInfo =  config.jsonPathTemplateFiles().get(CodegenConstants.JSON_PATH_LOCATION_TYPE.REQUEST_BODY);
         if (templateInfo != null && !templateInfo.isEmpty()) {
@@ -852,7 +859,10 @@ private void generateRequestBody(List<File> files, CodegenRequestBody requestBod
             return;
         }
         // doc generation
-        Boolean generateRequestBodyDocumentaion = Boolean.TRUE;
+        Boolean generateRequestBodyDocumentation = Boolean.TRUE;
+        templateData.put("headerSize", "#");
+        templateData.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+        templateData.put("identifierToHeadingQty", new HashMap<>());
         String componentName = jsonPath.substring(jsonPath.lastIndexOf("/") + 1);
         for (Map.Entry<String, String> entry: config.requestBodyDocTemplateFiles().entrySet()) {
             String templateName = entry.getKey();
@@ -862,7 +872,7 @@ private void generateRequestBody(List<File> files, CodegenRequestBody requestBod
 
             templateData.put("complexTypePrefix", "../../components/schema/");
             try {
-                File written = processTemplateToFile(templateData, templateName, filename, generateRequestBodyDocumentaion, CodegenConstants.REQUEST_BODY_DOCS);
+                File written = processTemplateToFile(templateData, templateName, filename, generateRequestBodyDocumentation, CodegenConstants.REQUEST_BODY_DOCS);
                 if (written != null) {
                     files.add(written);
                     if (config.isEnablePostProcessFile() && !dryRun) {
@@ -962,6 +972,9 @@ private TreeMap<String, CodegenParameter> generateParameters(List<File> files) {
                 Map<String, Object> templateData = new HashMap<>();
                 templateData.put("packageName", config.packageName());
                 templateData.put("parameter", parameter);
+                templateData.put("headerSize", "#");
+                templateData.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+                templateData.put("identifierToHeadingQty", new HashMap<>());
                 templateData.put("complexTypePrefix", "../../components/schema/");
 
                 try {
@@ -1066,6 +1079,7 @@ private TreeMap<String, CodegenHeader> generateHeaders(List<File> files) {
 
             generateHeader(files, header, sourceJsonPath);
 
+            // documentation
             Boolean generateHeaderDocs = Boolean.TRUE;
             for (Map.Entry<String, String> headerDocInfo : config.headerDocTemplateFiles().entrySet()) {
                 String templateName = headerDocInfo.getKey();
@@ -1075,8 +1089,12 @@ private TreeMap<String, CodegenHeader> generateHeaders(List<File> files) {
                 Map<String, Object> templateData = new HashMap<>();
                 templateData.put("packageName", config.packageName());
                 templateData.put("header", header);
+                templateData.put("headerSize", "#");
                 templateData.put("complexTypePrefix", "../../components/schema/");
                 templateData.put("docRoot", "../../");
+                templateData.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+                templateData.put("identifierToHeadingQty", new HashMap<>());
+
 
                 try {
                     File written = processTemplateToFile(templateData, templateName, filename, generateHeaderDocs, CodegenConstants.HEADER_DOCS, fileFolder);
@@ -1161,6 +1179,8 @@ protected TreeMap<String, CodegenSchema> generateSchemas(List<File> files) {
                 generateModelTests(files, schemaData, componentName);
 
                 // to generate model documentation files
+                schemaData.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+                schemaData.put("identifierToHeadingQty", new HashMap<>());
                 generateModelDocumentation(files, schemaData, componentName);
 
             } catch (Exception e) {

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

@@ -7,12 +7,14 @@ public class CodegenKey {
     public final boolean isValid;
     public final String snakeCase;
     public final String camelCase;
+    public final String anchorPiece;
 
-    public CodegenKey(String original, boolean isValid, String snakeCase, String camelCase) {
+    public CodegenKey(String original, boolean isValid, String snakeCase, String camelCase, String anchorPiece) {
         this.original = original;
         this.isValid = isValid;
         this.snakeCase = snakeCase;
         this.camelCase = camelCase;
+        this.anchorPiece = anchorPiece;
     }
 
     @Override
@@ -23,11 +25,12 @@ public boolean equals(Object o) {
         return Objects.equals(original, that.original) &&
                 Objects.equals(isValid, that.isValid) &&
                 Objects.equals(snakeCase, that.snakeCase) &&
-                Objects.equals(camelCase, that.camelCase);
+                Objects.equals(camelCase, that.camelCase) &&
+                Objects.equals(anchorPiece, that.anchorPiece);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(original, isValid, snakeCase, camelCase);
+        return Objects.hash(original, isValid, snakeCase, camelCase, anchorPiece);
     }
 }

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

@@ -26,7 +26,7 @@
 public class CodegenOperation {
     public final Boolean deprecated;
     public final boolean hasErrorResponseObject; // if 4xx, 5xx responses have at least one error object defined
-    public final String summary, unescapedNotes, notes;
+    public final String summary, unescapedDescription, description;
     public final CodegenKey httpMethod;
     public final CodegenKey path;
     public final LinkedHashSet<String> produces;
@@ -51,12 +51,12 @@ public class CodegenOperation {
     public final Map<String, Object> vendorExtensions;
     public final CodegenKey operationId;
 
-    public CodegenOperation(Boolean deprecated, boolean hasErrorResponseObject, String summary, String unescapedNotes, String notes, CodegenKey httpMethod, CodegenKey path, LinkedHashSet<String> produces, List<CodegenServer> servers, CodegenRequestBody requestBody, List<CodegenParameter> allParams, List<CodegenParameter> pathParams, List<CodegenParameter> queryParams, List<CodegenParameter> headerParams, List<CodegenParameter> cookieParams, boolean hasRequiredParamOrBody, boolean hasOptionalParamOrBody, List<CodegenSecurity> authMethods, Map<String, CodegenTag> tags, TreeMap<String, CodegenResponse> responses, TreeMap<Integer, CodegenResponse> statusCodeResponses, TreeMap<Integer, CodegenResponse> wildcardCodeResponses, TreeMap<String, CodegenResponse> nonDefaultResponses, CodegenResponse defaultResponse, List<CodegenCallback> callbacks, ExternalDocumentation externalDocs, Map<String, Object> vendorExtensions, CodegenKey operationId) {
+    public CodegenOperation(Boolean deprecated, boolean hasErrorResponseObject, String summary, String unescapedDescription, String description, CodegenKey httpMethod, CodegenKey path, LinkedHashSet<String> produces, List<CodegenServer> servers, CodegenRequestBody requestBody, List<CodegenParameter> allParams, List<CodegenParameter> pathParams, List<CodegenParameter> queryParams, List<CodegenParameter> headerParams, List<CodegenParameter> cookieParams, boolean hasRequiredParamOrBody, boolean hasOptionalParamOrBody, List<CodegenSecurity> authMethods, Map<String, CodegenTag> tags, TreeMap<String, CodegenResponse> responses, TreeMap<Integer, CodegenResponse> statusCodeResponses, TreeMap<Integer, CodegenResponse> wildcardCodeResponses, TreeMap<String, CodegenResponse> nonDefaultResponses, CodegenResponse defaultResponse, List<CodegenCallback> callbacks, ExternalDocumentation externalDocs, Map<String, Object> vendorExtensions, CodegenKey operationId) {
         this.deprecated = deprecated;
         this.hasErrorResponseObject = hasErrorResponseObject;
         this.summary = summary;
-        this.unescapedNotes = unescapedNotes;
-        this.notes = notes;
+        this.unescapedDescription = unescapedDescription;
+        this.description = description;
         this.httpMethod = httpMethod;
         this.path = path;
         this.produces = produces;
@@ -131,8 +131,8 @@ public String toString() {
         sb.append(", operationId='").append(operationId).append('\'');
         sb.append(", httpMethod='").append(httpMethod).append('\'');
         sb.append(", summary='").append(summary).append('\'');
-        sb.append(", unescapedNotes='").append(unescapedNotes).append('\'');
-        sb.append(", notes='").append(notes).append('\'');
+        sb.append(", unescapedNotes='").append(unescapedDescription).append('\'');
+        sb.append(", notes='").append(description).append('\'');
         sb.append(", defaultResponse='").append(defaultResponse).append('\'');
         sb.append(", produces=").append(produces);
         sb.append(", servers=").append(servers);
@@ -167,8 +167,8 @@ public boolean equals(Object o) {
                 Objects.equals(operationId, that.operationId) &&
                 Objects.equals(httpMethod, that.httpMethod) &&
                 Objects.equals(summary, that.summary) &&
-                Objects.equals(unescapedNotes, that.unescapedNotes) &&
-                Objects.equals(notes, that.notes) &&
+                Objects.equals(unescapedDescription, that.unescapedDescription) &&
+                Objects.equals(description, that.description) &&
                 Objects.equals(defaultResponse, that.defaultResponse) &&
                 Objects.equals(produces, that.produces) &&
                 Objects.equals(servers, that.servers) &&
@@ -195,7 +195,7 @@ public boolean equals(Object o) {
     public int hashCode() {
 
         return Objects.hash(deprecated, path, operationId, httpMethod,
-                summary, unescapedNotes, notes, defaultResponse,
+                summary, unescapedDescription, description, defaultResponse,
                 produces, servers, requestBody, allParams,
                 pathParams, queryParams, headerParams, cookieParams, hasRequiredParamOrBody, hasOptionalParamOrBody,
                 authMethods, tags, responses, callbacks, externalDocs,

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

@@ -41,6 +41,41 @@ public CodegenResponse(CodegenKey jsonPathPiece, Map<String, CodegenHeader> head
         this.componentModule = componentModule;
     }
 
+    /**
+     * Used by templates to only render body details if there is a schema defined for a content type
+     * @return true if there is an inline header
+     */
+    public boolean hasContentSchema() {
+        if (content == null) {
+            return false;
+        }
+        for (CodegenMediaType mediaType: content.values()) {
+            if (mediaType == null) {
+                continue;
+            }
+            if (mediaType.schema != null) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Used by templates to only render header details if there is an inline header
+     * @return true if there is an inline header
+     */
+    public boolean hasInlineHeader() {
+        if (headers == null) {
+            return false;
+        }
+        for (CodegenHeader header: headers.values()) {
+            if (header.refInfo == null) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     @Override
     public int hashCode() {
         return Objects.hash(jsonPathPiece, description,

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

@@ -32,6 +32,7 @@
 import com.github.jknack.handlebars.io.TemplateSource;
 import org.openapijsonschematools.codegen.api.AbstractTemplatingEngineAdapter;
 import org.openapijsonschematools.codegen.api.TemplatingExecutor;
+import org.openapijsonschematools.codegen.templating.handlebars.CustomHelpers;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -87,7 +88,7 @@ public TemplateSource sourceAt(String location) {
         StringHelpers.register(handlebars);
         handlebars.registerHelpers(ConditionalHelpers.class);
         handlebars.registerHelpers(org.openapijsonschematools.codegen.templating.handlebars.StringHelpers.class);
-        handlebars.registerHelpers(org.openapijsonschematools.codegen.templating.handlebars.ContainsHelper.class);
+        handlebars.registerHelpers(CustomHelpers.class);
         handlebars.setInfiniteLoops(infiniteLoops);
         handlebars.setPrettyPrint(prettyPrint);
         Template tmpl = handlebars.compile(templateFile);