v2 improves endpoint doc paths (#143)

* Adds method info to operation docs, moves the docs

* Fixes endpoint doc links

* Updates readme endpoint links

* Updates endpoint url links

* Samples regen

Author: spacether

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

@@ -463,32 +463,20 @@ private void generatePathItem(List<File> files, CodegenKey pathKey, CodegenPathI
                 generateXs(files, operationJsonPath, CodegenConstants.JSON_PATH_LOCATION_TYPE.OPERATION, CodegenConstants.APIS, endpointMap, true);
 
                 // operation docs
-                Map<String, String> templateToSuffix = config.jsonPathDocTemplateFiles().get(CodegenConstants.JSON_PATH_LOCATION_TYPE.OPERATION);
-                if (templateToSuffix != null) {
-                    for (Map.Entry<String, String> templateToSuffixEntry: templateToSuffix.entrySet()) {
-                        String templateFile = templateToSuffixEntry.getKey();
-                        String suffix = templateToSuffixEntry.getValue();
-                        for (Map.Entry<String, CodegenTag> tagEntry: operation.tags.entrySet()) {
-                            CodegenTag tag = tagEntry.getValue();
-                            Map<String, Object> endpointInfo = new HashMap<>();
-                            endpointInfo.put("operation", operation);
-                            endpointInfo.put("httpMethod", httpMethod);
-                            endpointInfo.put("path", pathKey);
-                            endpointInfo.put("pathItem", pathItem);
-                            endpointInfo.put("servers", servers);
-                            endpointInfo.put("security", security);
-                            endpointInfo.put("packageName", config.packageName());
-                            endpointInfo.put("apiPackage", config.apiPackage());
-                            endpointInfo.put("tag", tag);
-                            endpointInfo.put("headerSize", "#");
-                            endpointInfo.put("complexTypePrefix", "../../../components/schema/");
-                            endpointInfo.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
-                            endpointInfo.put("identifierToHeadingQty", new HashMap<>());
-                            String outputFilename = filenameFromRoot(Arrays.asList("docs", config.apiPackage(), "tags", tag.moduleName, operation.operationId.snakeCase + suffix));
-                            generateFile(endpointInfo, templateFile, outputFilename, files, true, CodegenConstants.APIS);
-                        }
-                    }
-                }
+                Map<String, Object> endpointInfo = new HashMap<>();
+                endpointInfo.put("operation", operation);
+                endpointInfo.put("httpMethod", httpMethod);
+                endpointInfo.put("path", pathKey);
+                endpointInfo.put("pathItem", pathItem);
+                endpointInfo.put("servers", servers);
+                endpointInfo.put("security", security);
+                endpointInfo.put("packageName", config.packageName());
+                endpointInfo.put("apiPackage", config.apiPackage());
+                endpointInfo.put("headerSize", "#");
+                endpointInfo.put("complexTypePrefix", "../../components/schema/");
+                endpointInfo.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
+                endpointInfo.put("identifierToHeadingQty", new HashMap<>());
+                generateXDocs(files, operationJsonPath, CodegenConstants.JSON_PATH_LOCATION_TYPE.OPERATION, CodegenConstants.APIS, endpointInfo, true);
 
                 // paths.some_path.security.security_requirement_0.py
                 if (operation.security != null) {
@@ -1056,7 +1044,7 @@ void generateApis(List<File> files, TreeMap<CodegenKey, CodegenPathItem> paths)
         }
 
         HashMap<CodegenTag, HashMap<CodegenKey, ArrayList<CodegenOperation>>> tagToPathToOperations = new HashMap<>();
-        HashMap<CodegenTag, TreeMap<CodegenKey, CodegenOperation>> tagToOperationIdToOperation = new HashMap<>();
+        HashMap<CodegenTag, TreeMap<CodegenKey, HashMap<CodegenKey, CodegenOperation>>> tagToOperationIdToPathToOperation = new HashMap<>();
         Map<String, String> apiPathTemplates = config.jsonPathTemplateFiles().get(CodegenConstants.JSON_PATH_LOCATION_TYPE.API_PATH);
         for(Map.Entry<CodegenKey, CodegenPathItem> entry: paths.entrySet()) {
             CodegenKey path = entry.getKey();
@@ -1085,16 +1073,18 @@ void generateApis(List<File> files, TreeMap<CodegenKey, CodegenPathItem> paths)
                     }
                     if (!tagToPathToOperations.containsKey(tag)) {
                         tagToPathToOperations.put(tag, new HashMap<>());
-                        tagToOperationIdToOperation.put(tag, new TreeMap<>());
+                        tagToOperationIdToPathToOperation.put(tag, new TreeMap<>());
                     }
                     HashMap<CodegenKey, ArrayList<CodegenOperation>> pathToOperations = tagToPathToOperations.get(tag);
                     if (!pathToOperations.containsKey(path)) {
                         pathToOperations.put(path, new ArrayList<>());
                     }
                     pathToOperations.get(path).add(op);
-                    TreeMap<CodegenKey, CodegenOperation> operationIdToOperation = tagToOperationIdToOperation.get(tag);
-                    if (!operationIdToOperation.containsKey(op.operationId)) {
-                        operationIdToOperation.put(op.operationId, op);
+                    TreeMap<CodegenKey, HashMap<CodegenKey, CodegenOperation>> operationIdToPathToOperation = tagToOperationIdToPathToOperation.get(tag);
+                    if (!operationIdToPathToOperation.containsKey(op.operationId)) {
+                        HashMap<CodegenKey, CodegenOperation> pathToOperation = new HashMap<>();
+                        pathToOperation.put(path, op);
+                        operationIdToPathToOperation.put(op.operationId, pathToOperation);
                     }
                 }
             }
@@ -1152,9 +1142,9 @@ public int compare(CodegenKey e1, CodegenKey e2) {
                 }
             }
 
-            TreeMap<CodegenKey, CodegenOperation> operationIdToOperation = new TreeMap<>(new OperationIdComparator());
-            operationIdToOperation.putAll(tagToOperationIdToOperation.get(tag));
-            apiData.put("operationIdToOperation", operationIdToOperation);
+            TreeMap<CodegenKey, HashMap<CodegenKey, CodegenOperation>> operationIdToPathToOperation = new TreeMap<>(new OperationIdComparator());
+            operationIdToPathToOperation.putAll(tagToOperationIdToPathToOperation.get(tag));
+            apiData.put("operationIdToPathToOperation", operationIdToPathToOperation);
 
             if (apiTagTemplates != null) {
                 for (Map.Entry<String, String> apiPathEntry: apiTagTemplates.entrySet()) {

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

@@ -43,7 +43,7 @@ HTTP request | Method | Description
 ------------ | ------ | -------------
 {{#each paths}}
 {{#each operations}}
-{{../@key.original}} **{{@key.original}}** | {{#each tags}}[{{className}}]({{apiDocPath}}{{moduleName}}.md).[{{operationId.snakeCase}}]({{apiDocPath}}{{moduleName}}/{{operationId.snakeCase}}.md) {{/each}} | {{#if summary}}{{summary}}{{/if}}
+{{../@key.original}} **{{@key.original}}** | {{#each tags}}[{{className}}]({{apiDocPath}}{{moduleName}}.md).[{{operationId.snakeCase}}](docs/paths/{{../../@key.snakeCase}}/{{../@key.original}}.md) {{/each}} | {{#if summary}}{{summary}}{{/if}}
 {{/each}}
 {{/each}}
 {{/if}}

modules/openapi-json-schema-generator/src/main/resources/python/apis/tags/api_doc.hbs

@@ -16,8 +16,10 @@ All URIs are relative to the selected server
 
 Method | Description
 ------ | -------------
-{{#each operationIdToOperation}}
-[**{{@key.snakeCase}}**]({{tag.moduleName}}/{{operationId.snakeCase}}.md) | {{#if summary}}{{summary}}{{/if}}
+{{#each operationIdToPathToOperation}}
+    {{#each this}}
+[**{{../@key.snakeCase}}**](../../paths/{{@key.snakeCase}}/{{jsonPathPiece.original}}.md) | {{#if summary}}{{summary}}{{/if}}
+    {{/each}}
 {{/each}}
 
 [[Back to top]](#top) {{> _helper_footer_links readmePath="../../../" endpointsLink=true }}

modules/openapi-json-schema-generator/src/main/resources/python/paths/path/verb/operation_doc.hbs

@@ -1,6 +1,14 @@
 {{#with operation}}
-<a name="{{operationId.anchorPiece}}"></a>
-{{headerSize}} **{{{operationId.snakeCase}}}**
+{{packageName}}.paths.{{path.snakeCase}}.operation
+{{headerSize}} Operation Method Name
+
+| Method Name | Api Class | Notes |
+| ----------- | --------- | ----- |
+    {{#each tags}}
+| {{../operationId.snakeCase}} | [{{className}}](../../apis/tags/{{moduleName}}.md) | This api is only for tag={{{name}}} |
+    {{/each}}
+| {{httpMethod.original}} | ApiFor{{httpMethod.camelCase}} | This api is only for this endpoint |
+| {{httpMethod.original}} | {{path.camelCase}} | This api is only for path={{{path.original}}} |
 
 {{headerSize}}# Table of Contents
 - [General Info](#general-info)
@@ -40,9 +48,9 @@ Name | Type | Description  | Notes
         {{#if refInfo}}
             {{#with getDeepestRef}}
                 {{#if required}}
-[**body**](../../../components/request_bodies/{{../refInfo.refModule}}.md) | typing.Union[{{#each content}}{{#with this.schema}}[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.{{jsonPathPiece.snakeCase}}](../../../components/request_bodies/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" ../@key jsonPathPiece) }}){{/with}}, {{/each}}{{#each getContentSchemas}}{{> _helper_schema_python_types }}{{#unless @last}}, {{/unless}}{{/each}}] | required |
+[**body**](../../components/request_bodies/{{../refInfo.refModule}}.md) | typing.Union[{{#each content}}{{#with this.schema}}[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.{{jsonPathPiece.snakeCase}}](../../components/request_bodies/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" ../@key jsonPathPiece) }}){{/with}}, {{/each}}{{#each getContentSchemas}}{{> _helper_schema_python_types }}{{#unless @last}}, {{/unless}}{{/each}}] | required |
                 {{else}}
-[**body**](../../../components/request_bodies/{{../refInfo.refModule}}.md) | typing.Union[{{#each content}}{{#with this.schema}}[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.{{jsonPathPiece.snakeCase}}](../../../components/request_bodies/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" ../@key jsonPathPiece) }}){{/with}}, {{/each}}Unset, {{#each getContentSchemas}}{{> _helper_schema_python_types }}{{#unless @last}}, {{/unless}}{{/each}}] | optional, default is unset |
+[**body**](../../components/request_bodies/{{../refInfo.refModule}}.md) | typing.Union[{{#each content}}{{#with this.schema}}[{{../../../refInfo.refClass}}.content.{{../@key.snakeCase}}.{{jsonPathPiece.snakeCase}}](../../components/request_bodies/{{../../../refInfo.refModule}}.md#{{> components/_helper_anchor_id identifierPieces=(append identifierPieces "content" ../@key jsonPathPiece) }}){{/with}}, {{/each}}Unset, {{#each getContentSchemas}}{{> _helper_schema_python_types }}{{#unless @last}}, {{/unless}}{{/each}}] | optional, default is unset |
                 {{/if}}
             {{/with}}
         {{else}}
@@ -114,15 +122,15 @@ n/a | api_client.ApiResponseWithoutDeserialization | When skip_deserialization i
 {{#if defaultResponse}}
     {{#with defaultResponse}}
         {{#if refInfo}}
-default | [{{refInfo.refClass}}.response_cls](../../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
+default | [{{refInfo.refClass}}.response_cls](../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
         {{else}}
 default | [{{jsonPathPiece.camelCase}}.response_cls](#{{jsonPathPiece.anchorPiece}}-response_cls) | {{description}}
         {{/if}}
     {{/with}}
 {{/if}}
 {{#each nonDefaultResponses}}
     {{#if refInfo}}
-{{@key}} | [{{refInfo.refClass}}.response_cls](../../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
+{{@key}} | [{{refInfo.refClass}}.response_cls](../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
     {{else}}
 {{@key}} | [{{jsonPathPiece.camelCase}}.response_cls](#{{jsonPathPiece.anchorPiece}}-response_cls) | {{description}}
     {{/if}}
@@ -149,7 +157,7 @@ See how to do this in the code sample.
 | Security Index | Security Scheme to Scope Names |
 | -------------- | ------------------------------ |
         {{#each security}}
-| {{@key}}       | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
+| {{@key}}       | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
         {{/each}}
     {{/gt}}
 {{else}}
@@ -169,7 +177,7 @@ See how to do this in the code sample.
 | Security Index | Security Scheme to Scope Names |
 | -------------- | ------------------------------ |
             {{#each ../security}}
-| {{@key}}       | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
+| {{@key}}       | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
             {{/each}}
         {{/gt}}
     {{/neq}}
@@ -236,5 +244,9 @@ server_index | Class | Description
 
 {{> paths/path/verb/_helper_operation_doc_example rootSecurity=../security }}
 
-[[Back to top]](#top) [[Back to API]](../{{tag.moduleName}}.md) {{> _helper_footer_links readmePath="../../../../" endpointsLink=true}}
+[[Back to top]](#top)
+    {{#each tags}}
+[[Back to {{className}} API]](../../apis/tags/{{moduleName}}.md)
+    {{/each}}
+{{> _helper_footer_links readmePath="../../../" endpointsLink=true}}
 {{/with}}