Skip to content

Commit edef852

Browse files
ckoegelckoegel
committed
[typescript-axios] Add Api and Model Docs
1 parent 07e5a67 commit edef852

4 files changed

Lines changed: 181 additions & 0 deletions

File tree

‎modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/TypeScriptAxiosClientCodegen.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
import org.openapitools.codegen.model.OperationsMap;
3232
import org.openapitools.codegen.utils.ModelUtils;
3333

34+
import java.io.File;
3435
import java.util.List;
3536
import java.util.Locale;
3637
import java.util.Map;
@@ -59,6 +60,9 @@ public class TypeScriptAxiosClientCodegen extends AbstractTypeScriptClientCodege
5960

6061
private String tsModelPackage = "";
6162

63+
protected String apiDocPath = "docs/";
64+
protected String modelDocPath = "docs/";
65+
6266
public TypeScriptAxiosClientCodegen() {
6367
super();
6468

@@ -126,6 +130,11 @@ public void processOpts() {
126130
additionalProperties.put("tsApiPackage", tsApiPackage);
127131
additionalProperties.put("apiRelativeToRoot", apiRelativeToRoot);
128132
additionalProperties.put("modelRelativeToRoot", modelRelativeToRoot);
133+
additionalProperties.put("apiDocPath", apiDocPath);
134+
additionalProperties.put("modelDocPath", modelDocPath);
135+
136+
modelDocTemplateFiles.put("model_doc.mustache", ".md");
137+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
129138

130139
supportingFiles.add(new SupportingFile("index.mustache", "", "index.ts"));
131140
supportingFiles.add(new SupportingFile("baseApi.mustache", "", "base.ts"));
@@ -276,6 +285,16 @@ public ModelsMap postProcessModels(ModelsMap objs) {
276285
return objs;
277286
}
278287

288+
@Override
289+
public String apiDocFileFolder() {
290+
return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
291+
}
292+
293+
@Override
294+
public String modelDocFileFolder() {
295+
return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
296+
}
297+
279298
/**
280299
* Overriding toRegularExpression() to avoid escapeText() being called,
281300
* as it would return a broken regular expression if any escaped character / metacharacter were present.

‎modules/openapi-generator/src/main/resources/typescript-axios/README.mustache‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,3 +44,53 @@ _unPublished (not recommended):_
4444
```
4545
npm install PATH_TO_GENERATED_PACKAGE --save
4646
```
47+
48+
### Documentation for API Endpoints
49+
50+
All URIs are relative to *{{{basePath}}}*
51+
52+
Class | Method | HTTP request | Description
53+
------------ | ------------- | ------------- | -------------
54+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{summary}}
55+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
56+
57+
### Documentation For Models
58+
59+
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
60+
{{/model}}{{/models}}
61+
62+
<a id="documentation-for-authorization"></a>
63+
## Documentation For Authorization
64+
65+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
66+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
67+
{{#authMethods}}
68+
<a id="{{name}}"></a>
69+
### {{{name}}}
70+
71+
{{#isApiKey}}
72+
- **Type**: API key
73+
- **API key parameter name**: {{{keyParamName}}}
74+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
75+
{{/isApiKey}}
76+
{{#isBasic}}
77+
{{#isBasicBasic}}
78+
- **Type**: HTTP basic authentication
79+
{{/isBasicBasic}}
80+
{{#isBasicBearer}}
81+
- **Type**: Bearer authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
82+
{{/isBasicBearer}}
83+
{{#isHttpSignature}}
84+
- **Type**: HTTP signature authentication
85+
{{/isHttpSignature}}
86+
{{/isBasic}}
87+
{{#isOAuth}}
88+
- **Type**: OAuth
89+
- **Flow**: {{{flow}}}
90+
- **Authorization URL**: {{{authorizationUrl}}}
91+
- **Scopes**: {{^scopes}}N/A{{/scopes}}
92+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
93+
{{/scopes}}
94+
{{/isOAuth}}
95+
96+
{{/authMethods}}

‎modules/openapi-generator/src/main/resources/typescript-axios/api_doc.mustache‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# {{classname}}{{#description}}
2+
3+
{{description}}{{/description}}
4+
5+
All URIs are relative to *{{basePath}}*
6+
7+
|Method | HTTP request | Description|
8+
|------------- | ------------- | -------------|
9+
{{#operations}}{{#operation}}|[**{{operationId}}**](#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}|
10+
{{/operation}}
11+
{{/operations}}
12+
13+
{{#operations}}
14+
{{#operation}}
15+
# **{{{operationId}}}**
16+
> {{#returnType}}{{{returnType}}} {{/returnType}}{{{operationId}}}({{#requiredParams}}{{^defaultValue}}{{paramName}}{{^-last}}, {{/-last}}{{/defaultValue}}{{/requiredParams}})
17+
18+
{{#notes}}
19+
{{{notes}}}
20+
{{/notes}}
21+
22+
### Example
23+
24+
```typescript
25+
import {
26+
{{classname}},
27+
Configuration{{#allParams}}{{#isModel}},
28+
{{{dataType}}}{{/isModel}}{{/allParams}}
29+
} from '{{{npmName}}}';
30+
31+
const configuration = new Configuration();
32+
const apiInstance = new {{classname}}(configuration);
33+
{{#hasParams}}{{#allParams}}
34+
let {{paramName}}: {{{dataType}}}; //{{{description}}}{{^required}} (optional){{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}{{/allParams}}
35+
36+
const { status, data } = await apiInstance.{{{operationId}}}({{#allParams}}
37+
{{paramName}}{{^-last}},{{/-last}}{{/allParams}}
38+
);
39+
{{/hasParams}}{{^hasParams}}
40+
const { status, data } = await apiInstance.{{{operationId}}}();
41+
{{/hasParams}}
42+
```
43+
44+
### Parameters
45+
{{^hasParams}}This endpoint does not have any parameters.{{/hasParams}}{{#allParams}}{{#-last}}
46+
|Name | Type | Description | Notes|
47+
|------------- | ------------- | ------------- | -------------|{{/-last}}{{/allParams}}
48+
{{#allParams}}{{^defaultValue}}| **{{paramName}}** | {{^isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}| {{description}} | |
49+
{{/defaultValue}}{{/allParams}}{{#allParams}}{{#defaultValue}}| **{{paramName}}** | {{^isPrimitiveType}}{{^isEnum}}**{{dataType}}**{{/isEnum}}{{/isPrimitiveType}}{{#isPrimitiveType}}[**{{dataType}}**]{{/isPrimitiveType}}{{#isEnum}}{{#allowableValues}}{{#enumVars}}{{#-first}}**Array<{{/-first}}{{value}}{{^-last}} &#124; {{/-last}}{{#-last}}>**{{/-last}}{{/enumVars}}{{/allowableValues}}{{/isEnum}} | {{description}} |{{^required}} (optional){{/required}} defaults to {{{.}}}|
50+
{{/defaultValue}}{{/allParams}}
51+
52+
### Return type
53+
54+
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
55+
56+
### Authorization
57+
58+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
59+
60+
### HTTP request headers
61+
62+
- **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
63+
- **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}}
64+
65+
{{#responses.0}}
66+
67+
### HTTP response details
68+
| Status code | Description | Response headers |
69+
|-------------|-------------|------------------|
70+
{{#responses}}
71+
|**{{code}}** | {{message}} | {{#headers}} * {{baseName}} - {{description}} <br> {{/headers}}{{^headers.0}} - {{/headers.0}} |
72+
{{/responses}}
73+
{{/responses.0}}
74+
75+
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
76+
77+
{{/operation}}
78+
{{/operations}}

‎modules/openapi-generator/src/main/resources/typescript-axios/model_doc.mustache‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{{#models}}{{#model}}# {{classname}}
2+
3+
{{#description}}{{&description}}
4+
{{/description}}
5+
6+
{{^isEnum}}
7+
## Properties
8+
9+
Name | Type | Description | Notes
10+
------------ | ------------- | ------------- | -------------
11+
{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#isReadOnly}}[readonly] {{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
12+
{{/vars}}
13+
14+
## Example
15+
16+
```typescript
17+
import { {{classname}} } from '{{npmName}}';
18+
19+
const instance: {{classname}} = {
20+
{{#vars}}
21+
{{name}},
22+
{{/vars}}
23+
};
24+
```
25+
26+
{{/isEnum}}
27+
{{#isEnum}}
28+
## Enum
29+
{{#allowableValues}}{{#enumVars}}
30+
* `{{name}}` (value: `{{{value}}}`)
31+
{{/enumVars}}{{/allowableValues}}
32+
{{/isEnum}}
33+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
34+
{{/model}}{{/models}}

0 commit comments

Comments
 (0)