Skip to content

Commit 11c5611

Browse files
ckoegelckoegel
authored
[typescript-axios] Add Api and Model Docs (#20969)
* [typescript-axios] Add Api and Model Docs * update templates for no `npmName` * generate samples
1 parent bd9d93d commit 11c5611

File tree

289 files changed

+23176
-0
lines changed

Some content is hidden

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

289 files changed

+23176
-0
lines changed

‎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}}{{.}}{{/npmName}}{{^npmName}}./api{{/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}}{{.}}{{/npmName}}{{^npmName}}./api{{/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}}

‎samples/client/echo_api/typescript-axios/build/.openapi-generator/FILES

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,24 @@ api.ts
55
base.ts
66
common.ts
77
configuration.ts
8+
docs/AuthApi.md
9+
docs/Bird.md
10+
docs/BodyApi.md
11+
docs/Category.md
12+
docs/DataQuery.md
13+
docs/DefaultValue.md
14+
docs/FormApi.md
15+
docs/HeaderApi.md
16+
docs/NumberPropertiesOnly.md
17+
docs/PathApi.md
18+
docs/Pet.md
19+
docs/Query.md
20+
docs/QueryApi.md
21+
docs/StringEnumRef.md
22+
docs/Tag.md
23+
docs/TestFormObjectMultipartRequestMarker.md
24+
docs/TestQueryStyleDeepObjectExplodeTrueObjectAllOfQueryObjectParameter.md
25+
docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md
826
git_push.sh
927
index.ts
1028
package.json

‎samples/client/echo_api/typescript-axios/build/README.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,3 +44,70 @@ _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 *http://localhost:3000*
51+
52+
Class | Method | HTTP request | Description
53+
------------ | ------------- | ------------- | -------------
54+
*AuthApi* | [**testAuthHttpBasic**](docs/AuthApi.md#testauthhttpbasic) | **POST** /auth/http/basic | To test HTTP basic authentication
55+
*AuthApi* | [**testAuthHttpBearer**](docs/AuthApi.md#testauthhttpbearer) | **POST** /auth/http/bearer | To test HTTP bearer authentication
56+
*BodyApi* | [**testBinaryGif**](docs/BodyApi.md#testbinarygif) | **POST** /binary/gif | Test binary (gif) response body
57+
*BodyApi* | [**testBodyApplicationOctetstreamBinary**](docs/BodyApi.md#testbodyapplicationoctetstreambinary) | **POST** /body/application/octetstream/binary | Test body parameter(s)
58+
*BodyApi* | [**testBodyMultipartFormdataArrayOfBinary**](docs/BodyApi.md#testbodymultipartformdataarrayofbinary) | **POST** /body/application/octetstream/array_of_binary | Test array of binary in multipart mime
59+
*BodyApi* | [**testBodyMultipartFormdataSingleBinary**](docs/BodyApi.md#testbodymultipartformdatasinglebinary) | **POST** /body/application/octetstream/single_binary | Test single binary in multipart mime
60+
*BodyApi* | [**testEchoBodyAllOfPet**](docs/BodyApi.md#testechobodyallofpet) | **POST** /echo/body/allOf/Pet | Test body parameter(s)
61+
*BodyApi* | [**testEchoBodyFreeFormObjectResponseString**](docs/BodyApi.md#testechobodyfreeformobjectresponsestring) | **POST** /echo/body/FreeFormObject/response_string | Test free form object
62+
*BodyApi* | [**testEchoBodyPet**](docs/BodyApi.md#testechobodypet) | **POST** /echo/body/Pet | Test body parameter(s)
63+
*BodyApi* | [**testEchoBodyPetResponseString**](docs/BodyApi.md#testechobodypetresponsestring) | **POST** /echo/body/Pet/response_string | Test empty response body
64+
*BodyApi* | [**testEchoBodyStringEnum**](docs/BodyApi.md#testechobodystringenum) | **POST** /echo/body/string_enum | Test string enum response body
65+
*BodyApi* | [**testEchoBodyTagResponseString**](docs/BodyApi.md#testechobodytagresponsestring) | **POST** /echo/body/Tag/response_string | Test empty json (request body)
66+
*FormApi* | [**testFormIntegerBooleanString**](docs/FormApi.md#testformintegerbooleanstring) | **POST** /form/integer/boolean/string | Test form parameter(s)
67+
*FormApi* | [**testFormObjectMultipart**](docs/FormApi.md#testformobjectmultipart) | **POST** /form/object/multipart | Test form parameter(s) for multipart schema
68+
*FormApi* | [**testFormOneof**](docs/FormApi.md#testformoneof) | **POST** /form/oneof | Test form parameter(s) for oneOf schema
69+
*HeaderApi* | [**testHeaderIntegerBooleanStringEnums**](docs/HeaderApi.md#testheaderintegerbooleanstringenums) | **GET** /header/integer/boolean/string/enums | Test header parameter(s)
70+
*PathApi* | [**testsPathStringPathStringIntegerPathIntegerEnumNonrefStringPathEnumRefStringPath**](docs/PathApi.md#testspathstringpathstringintegerpathintegerenumnonrefstringpathenumrefstringpath) | **GET** /path/string/{path_string}/integer/{path_integer}/{enum_nonref_string_path}/{enum_ref_string_path} | Test path parameter(s)
71+
*QueryApi* | [**testEnumRefString**](docs/QueryApi.md#testenumrefstring) | **GET** /query/enum_ref_string | Test query parameter(s)
72+
*QueryApi* | [**testQueryDatetimeDateString**](docs/QueryApi.md#testquerydatetimedatestring) | **GET** /query/datetime/date/string | Test query parameter(s)
73+
*QueryApi* | [**testQueryIntegerBooleanString**](docs/QueryApi.md#testqueryintegerbooleanstring) | **GET** /query/integer/boolean/string | Test query parameter(s)
74+
*QueryApi* | [**testQueryStyleDeepObjectExplodeTrueObject**](docs/QueryApi.md#testquerystyledeepobjectexplodetrueobject) | **GET** /query/style_deepObject/explode_true/object | Test query parameter(s)
75+
*QueryApi* | [**testQueryStyleDeepObjectExplodeTrueObjectAllOf**](docs/QueryApi.md#testquerystyledeepobjectexplodetrueobjectallof) | **GET** /query/style_deepObject/explode_true/object/allOf | Test query parameter(s)
76+
*QueryApi* | [**testQueryStyleFormExplodeFalseArrayInteger**](docs/QueryApi.md#testquerystyleformexplodefalsearrayinteger) | **GET** /query/style_form/explode_false/array_integer | Test query parameter(s)
77+
*QueryApi* | [**testQueryStyleFormExplodeFalseArrayString**](docs/QueryApi.md#testquerystyleformexplodefalsearraystring) | **GET** /query/style_form/explode_false/array_string | Test query parameter(s)
78+
*QueryApi* | [**testQueryStyleFormExplodeTrueArrayString**](docs/QueryApi.md#testquerystyleformexplodetruearraystring) | **GET** /query/style_form/explode_true/array_string | Test query parameter(s)
79+
*QueryApi* | [**testQueryStyleFormExplodeTrueObject**](docs/QueryApi.md#testquerystyleformexplodetrueobject) | **GET** /query/style_form/explode_true/object | Test query parameter(s)
80+
*QueryApi* | [**testQueryStyleFormExplodeTrueObjectAllOf**](docs/QueryApi.md#testquerystyleformexplodetrueobjectallof) | **GET** /query/style_form/explode_true/object/allOf | Test query parameter(s)
81+
82+
83+
### Documentation For Models
84+
85+
- [Bird](docs/Bird.md)
86+
- [Category](docs/Category.md)
87+
- [DataQuery](docs/DataQuery.md)
88+
- [DefaultValue](docs/DefaultValue.md)
89+
- [NumberPropertiesOnly](docs/NumberPropertiesOnly.md)
90+
- [Pet](docs/Pet.md)
91+
- [Query](docs/Query.md)
92+
- [StringEnumRef](docs/StringEnumRef.md)
93+
- [Tag](docs/Tag.md)
94+
- [TestFormObjectMultipartRequestMarker](docs/TestFormObjectMultipartRequestMarker.md)
95+
- [TestQueryStyleDeepObjectExplodeTrueObjectAllOfQueryObjectParameter](docs/TestQueryStyleDeepObjectExplodeTrueObjectAllOfQueryObjectParameter.md)
96+
- [TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter](docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md)
97+
98+
99+
<a id="documentation-for-authorization"></a>
100+
## Documentation For Authorization
101+
102+
103+
Authentication schemes defined for the API:
104+
<a id="http_auth"></a>
105+
### http_auth
106+
107+
- **Type**: HTTP basic authentication
108+
109+
<a id="http_bearer_auth"></a>
110+
### http_bearer_auth
111+
112+
- **Type**: Bearer authentication
113+

0 commit comments

Comments
 (0)