feat(typescript-fetch): add docs support

aheckmann · aheckmann · commit f8221eca4de9 · 2025-08-11T17:55:07.000-07:00
fixes #18276
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/TypeScriptFetchClientCodegen.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/TypeScriptFetchClientCodegen.java
@@ -73,6 +73,8 @@ public class TypeScriptFetchClientCodegen extends AbstractTypeScriptClientCodege
     protected boolean withoutRuntimeChecks = false;
     protected boolean stringEnums = false;
     protected String fileNaming = PASCAL_CASE;
+    protected String apiDocPath = "docs";
+    protected String modelDocPath = "docs";
 
     // "Saga and Record" mode.
     public static final String SAGAS_AND_RECORDS = "sagasAndRecords";
@@ -107,10 +109,14 @@ public TypeScriptFetchClientCodegen() {
         // at the moment
         importMapping.clear();
 
-        outputFolder = "generated-code/typescript-fetch";
+        outputFolder = "generated-code" + File.separator + "typescript-fetch";
         embeddedTemplateDir = templateDir = "typescript-fetch";
 
         this.apiTemplateFiles.put("apis.mustache", ".ts");
+        this.modelTemplateFiles.put("models.mustache", ".ts");
+
+        this.apiDocTemplateFiles.put("api_doc.mustache", ".md");
+        this.modelDocTemplateFiles.put("model_doc.mustache", ".md");
 
         this.addExtraReservedWords();
 
@@ -138,6 +144,11 @@ public String toModelFilename(String name) {
         return convertUsingFileNamingConvention(super.toModelFilename(name));
     }
 
+    @Override
+    public String toModelDocFilename(String name) {
+        return toModelName(name);
+    }
+
     /**
      * Converts the original name according to the current <code>fileNaming</code> strategy.
      *
@@ -242,6 +253,10 @@ public void processOpts() {
         this.apiPackage = sourceDir + "apis";
         this.modelPackage = sourceDir + "models";
 
+        // make api and model doc path available in mustache template
+        additionalProperties.put("apiDocPath", apiDocPath);
+        additionalProperties.put("modelDocPath", modelDocPath);
+
         supportingFiles.add(new SupportingFile("index.mustache", sourceDir, "index.ts"));
         supportingFiles.add(new SupportingFile("runtime.mustache", sourceDir, "runtime.ts"));
 
@@ -316,6 +331,16 @@ public void processOpts() {
         setGenerateValidationAttributes(convertPropertyToBooleanAndWriteBack(VALIDATION_ATTRIBUTES));
     }
 
+    @Override
+    public String apiDocFileFolder() {
+        return (outputFolder + File.separator + apiDocPath);
+    }
+
+    @Override
+    public String modelDocFileFolder() {
+        return (outputFolder + File.separator + modelDocPath);
+    }
+
     @Override
     public String toEnumDefaultValue(String value, String datatype) {
         if (this.getSagasAndRecords()) {
diff --git a/modules/openapi-generator/src/main/resources/typescript-fetch/README.mustache b/modules/openapi-generator/src/main/resources/typescript-fetch/README.mustache
@@ -1,46 +1,127 @@
-## {{npmName}}@{{npmVersion}}
+# {{npmName}}@{{npmVersion}}
 
-This generator creates TypeScript/JavaScript client that utilizes [Fetch API](https://fetch.spec.whatwg.org/). The generated Node module can be used in the following environments:
+A TypeScript SDK client for the {{host}} API.
 
-Environment
-* Node.js
-* Webpack
-* Browserify
+## Usage
 
-Language level
-* ES5 - you must have a Promises/A+ library installed
-* ES6
+First, install the SDK from npm.
 
-Module system
-* CommonJS
-* ES6 module system
+```bash
+npm install {{npmName}} --save
+```
+
+Next, try it out.
+
+{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
+```ts
+{{>api_example}}
+```
+{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
+
+## Documentation
+
+### API Endpoints
+
+All URIs are relative to *{{basePath}}*
+
+| Class | Method | HTTP request | Description
+| ----- | ------ | ------------ | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}/{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+
+### Models
+
+{{#models}}{{#model}}- [{{{classname}}}]({{modelDocPath}}/{{{classname}}}.md){{/model}}
+{{/models}}
+
+### Authorization
+
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
+{{#authMethods}}
+<a id="{{name}}{{#isOAuth}}-{{flow}}{{/isOAuth}}"></a>
+#### {{name}}{{#isOAuth}} {{flow}}{{/isOAuth}}
+
+{{#isApiKey}}
+
+- **Type**: API key
+- **API key parameter name**: `{{keyParamName}}`
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasicBasic}}
+
+- **Type**: HTTP basic authentication
+{{/isBasicBasic}}
+{{#isBasicBearer}}
+
+- **Type**: HTTP Bearer Token authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
+{{/isBasicBearer}}
+{{#isHttpSignature}}
 
-It can be used in both TypeScript and JavaScript. In TypeScript, the definition will be automatically resolved via `package.json`. ([Reference](https://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html))
+- **Type**: HTTP signature authentication
+{{/isHttpSignature}}
+{{#isOAuth}}
+
+- **Type**: OAuth
+- **Flow**: {{flow}}
+- **Authorization URL**: {{authorizationUrl}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}}  - `{{scope}}`: {{description}}
+{{/scopes}}
+{{/isOAuth}}
+{{/authMethods}}
+
+## About
+
+This TypeScript SDK client supports the [Fetch API](https://fetch.spec.whatwg.org/)
+and is automatically generated by the
+[OpenAPI Generator](https://openapi-generator.tech) project:
+
+- API version: `{{appVersion}}`
+- Package version: `{{npmVersion}}`
+{{^hideGenerationTimestamp}}
+- Build date: `{{generatedDate}}`
+{{/hideGenerationTimestamp}}
+- Generator version: `{{generatorVersion}}`
+- Build package: `{{generatorClass}}`
+
+The generated npm module supports the following:
+
+- Environments
+  * Node.js
+  * Webpack
+  * Browserify
+- Language levels
+  * ES5 - you must have a Promises/A+ library installed
+  * ES6
+- Module systems
+  * CommonJS
+  * ES6 module system
+
+{{#infoUrl}}
+For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
+## Development
 
 ### Building
 
-To build and compile the typescript sources to javascript use:
-```
+To build the TypeScript source code, you need to have Node.js and npm installed.
+After cloning the repository, navigate to the project directory and run:
+
+```bash
 npm install
 npm run build
 ```
 
 ### Publishing
 
-First build the package then run `npm publish`
-
-### Consuming
-
-navigate to the folder of your consuming project and run one of the following commands.
+Once you've built the package, you can publish it to npm:
 
-_published:_
-
-```
-npm install {{npmName}}@{{npmVersion}} --save
+```bash
+npm publish
 ```
 
-_unPublished (not recommended):_
+## License
 
-```
-npm install PATH_TO_GENERATED_PACKAGE --save
-```
+[{{licenseInfo}}]({{{licenseUrl}}})
diff --git a/modules/openapi-generator/src/main/resources/typescript-fetch/api_doc.mustache b/modules/openapi-generator/src/main/resources/typescript-fetch/api_doc.mustache
@@ -0,0 +1,63 @@
+# {{classname}}{{#description}}
+
+{{.}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+{{#operations}}{{#operation}}| [**{{operationId}}**]({{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{commonPath}}{{path}} | {{summary}} |
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+
+## {{operationId}}
+
+> {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}})
+
+{{summary}}{{#notes}}
+
+{{.}}{{/notes}}
+
+### Example
+
+```ts
+{{>api_example}}
+```
+
+### Parameters
+
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|{{/-last}}{{/allParams}}
+{{#allParams}}| **{{paramName}}** | {{#isEnum}}{{#allowableValues}}{{#values}}`{{{.}}}`{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}{{/isEnum}}{{^isEnum}}{{#isModel}}[{{baseType}}]({{baseType}}.md){{/isModel}}{{^isModel}}`{{{dataType}}}`{{/isModel}}{{/isEnum}} | {{description}} |{{^required}} [Optional]{{/required}}{{^isContainer}}{{#defaultValue}} [Defaults to `{{.}}`]{{/defaultValue}}{{/isContainer}}{{#allowableValues}} [Enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} |
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{returnType}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}`void` (Empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}{{#isOAuth}} {{flow}}{{/isOAuth}}](../README.md#{{{name}}}{{#isOAuth}}-{{flow}}{{/isOAuth}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP request headers
+
+- **Content-Type**: {{#consumes}}`{{{mediaType}}}`{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+- **Accept**: {{#produces}}`{{{mediaType}}}`{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{#responses.0}}
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+{{#responses}}
+| **{{code}}** | {{message}} | {{#headers}} * {{baseName}} - {{description}} <br> {{/headers}}{{^headers.0}} - {{/headers.0}} |
+{{/responses}}
+{{/responses.0}}
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+{{/operation}}
+{{/operations}}
diff --git a/modules/openapi-generator/src/main/resources/typescript-fetch/api_example.mustache b/modules/openapi-generator/src/main/resources/typescript-fetch/api_example.mustache
@@ -0,0 +1,44 @@
+import {
+  Configuration,
+  {{classname}},
+} from '{{npmName}}';
+import type { {{operationIdCamelCase}}Request } from '{{npmName}}';
+
+async function example() {
+  console.log("🚀 Testing {{npmName}} SDK...");
+  {{#hasAuthMethods}}
+  const config = new Configuration({ {{#authMethods}}{{#isBasicBasic}}
+    // To configure HTTP basic authorization: {{{name}}}
+    username: "YOUR USERNAME",
+    password: "YOUR PASSWORD",{{/isBasicBasic}}{{#isBasicBearer}}
+    // Configure HTTP bearer authorization: {{{name}}}
+    accessToken: "YOUR BEARER TOKEN",{{/isBasicBearer}}{{#isOAuth}}
+    // To configure OAuth2 access token for authorization: {{{name}}} {{{flow}}}
+    accessToken: "YOUR ACCESS TOKEN",{{/isOAuth}}{{#isApiKey}}
+    // To configure API key authorization: {{{name}}}
+    apiKey: "YOUR API KEY",{{/isApiKey}}{{#isHttpSignature}}
+    // To configure HTTP signature authorization: {{{name}}}
+    headers: { "YOUR HEADER NAME": "YOUR SIGNATURE" },{{/isHttpSignature}}{{/authMethods}}
+  });
+  {{/hasAuthMethods}}
+  const api = new {{classname}}({{#hasAuthMethods}}config{{/hasAuthMethods}});
+
+  {{#hasParams}}
+  const body = {
+    {{#allParams}}
+    // {{{dataType}}}{{#description}} | {{{description}}}{{/description}}{{^required}} (optional){{/required}}
+    {{paramName}}: {{{example}}}{{^example}}...{{/example}},
+    {{/allParams}}
+  } satisfies {{operationIdCamelCase}}Request;
+
+  {{/hasParams}}
+  try {
+    const data = await api.{{{operationId}}}({{#hasParams}}body{{/hasParams}});
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
diff --git a/modules/openapi-generator/src/main/resources/typescript-fetch/model_doc.mustache b/modules/openapi-generator/src/main/resources/typescript-fetch/model_doc.mustache
@@ -0,0 +1,39 @@
+{{#models}}{{#model}}
+# {{classname}}
+
+{{#description}}{{&description}}
+{{/description}}
+
+## Properties
+
+Name | Type
+------------ | -------------
+{{#vars}}`{{name}}` | {{#isPrimitiveType}}{{dataType}}{{/isPrimitiveType}}{{^isPrimitiveType}}[{{dataType}}]({{complexType}}.md){{/isPrimitiveType}}
+{{/vars}}
+
+## Example
+
+```typescript
+import type { {{classname}} } from '{{npmName}}'
+
+// TODO: Update the object below with actual values
+const example = {
+{{#vars}}
+  "{{name}}": {{{example}}},
+{{/vars}}
+} satisfies {{classname}}
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as {{classname}}
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+{{/model}}{{/models}}
