Skip to content
This repository was archived by the owner on Dec 25, 2024. It is now read-only.

Commit fa5b24c

Browse files
spacetherspacether
authored
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
1 parent fd5d4f6 commit fa5b24c

1,047 files changed

Lines changed: 29788 additions & 77281 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 24 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -463,32 +463,20 @@ private void generatePathItem(List<File> files, CodegenKey pathKey, CodegenPathI
463463
generateXs(files, operationJsonPath, CodegenConstants.JSON_PATH_LOCATION_TYPE.OPERATION, CodegenConstants.APIS, endpointMap, true);
464464

465465
// operation docs
466-
Map<String, String> templateToSuffix = config.jsonPathDocTemplateFiles().get(CodegenConstants.JSON_PATH_LOCATION_TYPE.OPERATION);
467-
if (templateToSuffix != null) {
468-
for (Map.Entry<String, String> templateToSuffixEntry: templateToSuffix.entrySet()) {
469-
String templateFile = templateToSuffixEntry.getKey();
470-
String suffix = templateToSuffixEntry.getValue();
471-
for (Map.Entry<String, CodegenTag> tagEntry: operation.tags.entrySet()) {
472-
CodegenTag tag = tagEntry.getValue();
473-
Map<String, Object> endpointInfo = new HashMap<>();
474-
endpointInfo.put("operation", operation);
475-
endpointInfo.put("httpMethod", httpMethod);
476-
endpointInfo.put("path", pathKey);
477-
endpointInfo.put("pathItem", pathItem);
478-
endpointInfo.put("servers", servers);
479-
endpointInfo.put("security", security);
480-
endpointInfo.put("packageName", config.packageName());
481-
endpointInfo.put("apiPackage", config.apiPackage());
482-
endpointInfo.put("tag", tag);
483-
endpointInfo.put("headerSize", "#");
484-
endpointInfo.put("complexTypePrefix", "../../../components/schema/");
485-
endpointInfo.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
486-
endpointInfo.put("identifierToHeadingQty", new HashMap<>());
487-
String outputFilename = filenameFromRoot(Arrays.asList("docs", config.apiPackage(), "tags", tag.moduleName, operation.operationId.snakeCase + suffix));
488-
generateFile(endpointInfo, templateFile, outputFilename, files, true, CodegenConstants.APIS);
489-
}
490-
}
491-
}
466+
Map<String, Object> endpointInfo = new HashMap<>();
467+
endpointInfo.put("operation", operation);
468+
endpointInfo.put("httpMethod", httpMethod);
469+
endpointInfo.put("path", pathKey);
470+
endpointInfo.put("pathItem", pathItem);
471+
endpointInfo.put("servers", servers);
472+
endpointInfo.put("security", security);
473+
endpointInfo.put("packageName", config.packageName());
474+
endpointInfo.put("apiPackage", config.apiPackage());
475+
endpointInfo.put("headerSize", "#");
476+
endpointInfo.put("complexTypePrefix", "../../components/schema/");
477+
endpointInfo.put("identifierPieces", Collections.unmodifiableList(new ArrayList<>()));
478+
endpointInfo.put("identifierToHeadingQty", new HashMap<>());
479+
generateXDocs(files, operationJsonPath, CodegenConstants.JSON_PATH_LOCATION_TYPE.OPERATION, CodegenConstants.APIS, endpointInfo, true);
492480

493481
// paths.some_path.security.security_requirement_0.py
494482
if (operation.security != null) {
@@ -1056,7 +1044,7 @@ void generateApis(List<File> files, TreeMap<CodegenKey, CodegenPathItem> paths)
10561044
}
10571045

10581046
HashMap<CodegenTag, HashMap<CodegenKey, ArrayList<CodegenOperation>>> tagToPathToOperations = new HashMap<>();
1059-
HashMap<CodegenTag, TreeMap<CodegenKey, CodegenOperation>> tagToOperationIdToOperation = new HashMap<>();
1047+
HashMap<CodegenTag, TreeMap<CodegenKey, HashMap<CodegenKey, CodegenOperation>>> tagToOperationIdToPathToOperation = new HashMap<>();
10601048
Map<String, String> apiPathTemplates = config.jsonPathTemplateFiles().get(CodegenConstants.JSON_PATH_LOCATION_TYPE.API_PATH);
10611049
for(Map.Entry<CodegenKey, CodegenPathItem> entry: paths.entrySet()) {
10621050
CodegenKey path = entry.getKey();
@@ -1085,16 +1073,18 @@ void generateApis(List<File> files, TreeMap<CodegenKey, CodegenPathItem> paths)
10851073
}
10861074
if (!tagToPathToOperations.containsKey(tag)) {
10871075
tagToPathToOperations.put(tag, new HashMap<>());
1088-
tagToOperationIdToOperation.put(tag, new TreeMap<>());
1076+
tagToOperationIdToPathToOperation.put(tag, new TreeMap<>());
10891077
}
10901078
HashMap<CodegenKey, ArrayList<CodegenOperation>> pathToOperations = tagToPathToOperations.get(tag);
10911079
if (!pathToOperations.containsKey(path)) {
10921080
pathToOperations.put(path, new ArrayList<>());
10931081
}
10941082
pathToOperations.get(path).add(op);
1095-
TreeMap<CodegenKey, CodegenOperation> operationIdToOperation = tagToOperationIdToOperation.get(tag);
1096-
if (!operationIdToOperation.containsKey(op.operationId)) {
1097-
operationIdToOperation.put(op.operationId, op);
1083+
TreeMap<CodegenKey, HashMap<CodegenKey, CodegenOperation>> operationIdToPathToOperation = tagToOperationIdToPathToOperation.get(tag);
1084+
if (!operationIdToPathToOperation.containsKey(op.operationId)) {
1085+
HashMap<CodegenKey, CodegenOperation> pathToOperation = new HashMap<>();
1086+
pathToOperation.put(path, op);
1087+
operationIdToPathToOperation.put(op.operationId, pathToOperation);
10981088
}
10991089
}
11001090
}
@@ -1152,9 +1142,9 @@ public int compare(CodegenKey e1, CodegenKey e2) {
11521142
}
11531143
}
11541144

1155-
TreeMap<CodegenKey, CodegenOperation> operationIdToOperation = new TreeMap<>(new OperationIdComparator());
1156-
operationIdToOperation.putAll(tagToOperationIdToOperation.get(tag));
1157-
apiData.put("operationIdToOperation", operationIdToOperation);
1145+
TreeMap<CodegenKey, HashMap<CodegenKey, CodegenOperation>> operationIdToPathToOperation = new TreeMap<>(new OperationIdComparator());
1146+
operationIdToPathToOperation.putAll(tagToOperationIdToPathToOperation.get(tag));
1147+
apiData.put("operationIdToPathToOperation", operationIdToPathToOperation);
11581148

11591149
if (apiTagTemplates != null) {
11601150
for (Map.Entry<String, String> apiPathEntry: apiTagTemplates.entrySet()) {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ HTTP request | Method | Description
4343
------------ | ------ | -------------
4444
{{#each paths}}
4545
{{#each operations}}
46-
{{../@key.original}} **{{@key.original}}** | {{#each tags}}[{{className}}]({{apiDocPath}}{{moduleName}}.md).[{{operationId.snakeCase}}]({{apiDocPath}}{{moduleName}}/{{operationId.snakeCase}}.md) {{/each}} | {{#if summary}}{{summary}}{{/if}}
46+
{{../@key.original}} **{{@key.original}}** | {{#each tags}}[{{className}}]({{apiDocPath}}{{moduleName}}.md).[{{operationId.snakeCase}}](docs/paths/{{../../@key.snakeCase}}/{{../@key.original}}.md) {{/each}} | {{#if summary}}{{summary}}{{/if}}
4747
{{/each}}
4848
{{/each}}
4949
{{/if}}

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,10 @@ All URIs are relative to the selected server
1616

1717
Method | Description
1818
------ | -------------
19-
{{#each operationIdToOperation}}
20-
[**{{@key.snakeCase}}**]({{tag.moduleName}}/{{operationId.snakeCase}}.md) | {{#if summary}}{{summary}}{{/if}}
19+
{{#each operationIdToPathToOperation}}
20+
{{#each this}}
21+
[**{{../@key.snakeCase}}**](../../paths/{{@key.snakeCase}}/{{jsonPathPiece.original}}.md) | {{#if summary}}{{summary}}{{/if}}
22+
{{/each}}
2123
{{/each}}
2224
2325
[[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‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
{{#with operation}}
2-
<a name="{{operationId.anchorPiece}}"></a>
3-
{{headerSize}} **{{{operationId.snakeCase}}}**
2+
{{packageName}}.paths.{{path.snakeCase}}.operation
3+
{{headerSize}} Operation Method Name
4+
5+
| Method Name | Api Class | Notes |
6+
| ----------- | --------- | ----- |
7+
{{#each tags}}
8+
| {{../operationId.snakeCase}} | [{{className}}](../../apis/tags/{{moduleName}}.md) | This api is only for tag={{{name}}} |
9+
{{/each}}
10+
| {{httpMethod.original}} | ApiFor{{httpMethod.camelCase}} | This api is only for this endpoint |
11+
| {{httpMethod.original}} | {{path.camelCase}} | This api is only for path={{{path.original}}} |
412

513
{{headerSize}}# Table of Contents
614
- [General Info](#general-info)
@@ -40,9 +48,9 @@ Name | Type | Description | Notes
4048
{{#if refInfo}}
4149
{{#with getDeepestRef}}
4250
{{#if required}}
43-
[**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 |
51+
[**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 |
4452
{{else}}
45-
[**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 |
53+
[**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 |
4654
{{/if}}
4755
{{/with}}
4856
{{else}}
@@ -114,15 +122,15 @@ n/a | api_client.ApiResponseWithoutDeserialization | When skip_deserialization i
114122
{{#if defaultResponse}}
115123
{{#with defaultResponse}}
116124
{{#if refInfo}}
117-
default | [{{refInfo.refClass}}.response_cls](../../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
125+
default | [{{refInfo.refClass}}.response_cls](../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
118126
{{else}}
119127
default | [{{jsonPathPiece.camelCase}}.response_cls](#{{jsonPathPiece.anchorPiece}}-response_cls) | {{description}}
120128
{{/if}}
121129
{{/with}}
122130
{{/if}}
123131
{{#each nonDefaultResponses}}
124132
{{#if refInfo}}
125-
{{@key}} | [{{refInfo.refClass}}.response_cls](../../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
133+
{{@key}} | [{{refInfo.refClass}}.response_cls](../../components/responses/{{refInfo.refModule}}.md#{{refInfo.refModule}}response_cls) | {{#with getDeepestRef}}{{description}}{{/with}}
126134
{{else}}
127135
{{@key}} | [{{jsonPathPiece.camelCase}}.response_cls](#{{jsonPathPiece.anchorPiece}}-response_cls) | {{description}}
128136
{{/if}}
@@ -149,7 +157,7 @@ See how to do this in the code sample.
149157
| Security Index | Security Scheme to Scope Names |
150158
| -------------- | ------------------------------ |
151159
{{#each security}}
152-
| {{@key}} | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
160+
| {{@key}} | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
153161
{{/each}}
154162
{{/gt}}
155163
{{else}}
@@ -169,7 +177,7 @@ See how to do this in the code sample.
169177
| Security Index | Security Scheme to Scope Names |
170178
| -------------- | ------------------------------ |
171179
{{#each ../security}}
172-
| {{@key}} | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
180+
| {{@key}} | {{#eq this.size 0}}no security{{else}}{{#each this}}["{{{@key}}}"](../../components/security_schemes/{{this.refInfo.refModule}}.md) {{this.scopeNames}}<br>{{/each}}{{/eq}} |
173181
{{/each}}
174182
{{/gt}}
175183
{{/neq}}
@@ -236,5 +244,9 @@ server_index | Class | Description
236244
237245
{{> paths/path/verb/_helper_operation_doc_example rootSecurity=../security }}
238246
239-
[[Back to top]](#top) [[Back to API]](../{{tag.moduleName}}.md) {{> _helper_footer_links readmePath="../../../../" endpointsLink=true}}
247+
[[Back to top]](#top)
248+
{{#each tags}}
249+
[[Back to {{className}} API]](../../apis/tags/{{moduleName}}.md)
250+
{{/each}}
251+
{{> _helper_footer_links readmePath="../../../" endpointsLink=true}}
240252
{{/with}}

0 commit comments

Comments
 (0)