feat: generate API docs

huwshimi · huwshimi · commit 6c5ba16f39be · 2024-11-15T17:16:54.000+11:00
diff --git a/docs/src/pages/reference/configuration/output.md b/docs/src/pages/reference/configuration/output.md
@@ -386,6 +386,26 @@ Default Value: `en`.
 
 Give you the possibility to set the locale for the mock generation. It is used by faker, see the list of available options [here](https://fakerjs.dev/guide/localization.html#available-locales). It should also be strongly typed using `defineConfig`.
 
+### docs
+
+Type: `Boolean | Object`.
+
+Default Value: `false`.
+
+Will generate API docs using [TypeDoc](https://typedoc.org/). by default these docs will be in Markdown format.
+
+TypeDoc can be configured by creating a config file e.g. `typedoc.config.mjs` in your project root (see the [config docs](https://typedoc.org/options/configuration/#options) for a full list of supported file names) or by passing a config filename to the `config` option below.
+
+See the TypeDoc [configuration documentation](https://typedoc.org/options/) for more details.
+
+The `docs` option can take some properties to customize the generation if you set it to an object. If you set it to `true`, the default options will be used.
+
+#### config
+
+Type: `String`.
+
+Use to specify a TypeDoc config filename. This can be useful if your project already has a TypeDoc config for other docs.
+
 ### clean
 
 Type: `Boolean | String[]`.
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -50,6 +50,7 @@ export type NormalizedOutputOptions = {
   client: OutputClient | OutputClientFunc;
   httpClient: OutputHttpClient;
   clean: boolean | string[];
+  docs: boolean | OutputDocsOptions;
   prettier: boolean;
   tslint: boolean;
   biome: boolean;
@@ -174,6 +175,7 @@ export type OutputOptions = {
   client?: OutputClient | OutputClientFunc;
   httpClient?: OutputHttpClient;
   clean?: boolean | string[];
+  docs?: boolean | OutputDocsOptions;
   prettier?: boolean;
   tslint?: boolean;
   biome?: boolean;
@@ -239,6 +241,10 @@ export const OutputMode = {
 
 export type OutputMode = (typeof OutputMode)[keyof typeof OutputMode];
 
+export type OutputDocsOptions = {
+  config: string;
+};
+
 // TODO: add support for other mock types (like cypress or playwright)
 export const OutputMockType = {
   MSW: 'msw',
diff --git a/packages/orval/package.json b/packages/orval/package.json
@@ -75,6 +75,9 @@
     "lodash.uniq": "^4.5.0",
     "openapi3-ts": "4.2.2",
     "string-argv": "^0.3.2",
-    "tsconfck": "^2.0.1"
+    "tsconfck": "^2.0.1",
+    "typedoc": "0.26.11",
+    "typedoc-plugin-markdown": "4.2.10",
+    "typescript": "^5.6.3"
   }
 }
diff --git a/packages/orval/src/utils/options.ts b/packages/orval/src/utils/options.ts
@@ -148,6 +148,7 @@ export const normalizeOptions = async (
       mode: normalizeOutputMode(outputOptions.mode ?? mode),
       mock,
       clean: outputOptions.clean ?? clean ?? false,
+      docs: outputOptions.docs ?? false,
       prettier: outputOptions.prettier ?? prettier ?? false,
       tslint: outputOptions.tslint ?? tslint ?? false,
       biome: outputOptions.biome ?? biome ?? false,
diff --git a/packages/orval/src/write-specs.ts b/packages/orval/src/write-specs.ts
@@ -18,6 +18,7 @@ import {
 import chalk from 'chalk';
 import execa from 'execa';
 import fs from 'fs-extra';
+import { Application } from 'typedoc';
 import uniq from 'lodash.uniq';
 import { InfoObject } from 'openapi3-ts/oas30';
 import { executeHook } from './utils';
@@ -198,6 +199,51 @@ export const writeSpecs = async (
     }
   }
 
+  if (output.docs) {
+    try {
+      const app = await Application.bootstrapWithPlugins({
+        entryPoints: paths,
+        // Set the custom config location if it has been provided.
+        ...(typeof output.docs === 'object'
+          ? { options: output.docs.config }
+          : {}),
+        plugin: ['typedoc-plugin-markdown'],
+      });
+      // Set defaults if the have not been provided by the external config.
+      if (!app.options.isSet('readme')) {
+        app.options.setValue('readme', 'none');
+      }
+      if (!app.options.isSet('logLevel')) {
+        app.options.setValue('logLevel', 'None');
+      }
+      const project = await app.convert();
+      if (project) {
+        let out = 'docs';
+        if (app.options.isSet('out')) {
+          // Use the output location if it has been set in the external config.
+          out = app.options.getValue('out');
+        } else if (output.workspace) {
+          // Generate the docs in the workspace.
+          out = upath.join(output.workspace, 'docs');
+        } else if (output.target) {
+          const base = upath.dirname(output.target);
+          // Generate the docs along side the output target.
+          out = upath.join(base, 'docs');
+        }
+        await app.generateDocs(project, out);
+      } else {
+        throw new Error('TypeDoc not initialised');
+      }
+    } catch (e: any) {
+      const message =
+        e.exitCode === 1
+          ? e.stdout + e.stderr
+          : `⚠️  ${projectTitle ? `${projectTitle} - ` : ''}Unable to generate docs`;
+
+      log(chalk.yellow(message));
+    }
+  }
+
   createSuccessMessage(projectTitle);
 };
 
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -75,6 +75,9 @@`
`75`	`75`	`"lodash.uniq": "^4.5.0",`
`76`	`76`	`"openapi3-ts": "4.2.2",`
`77`	`77`	`"string-argv": "^0.3.2",`
`78`		`- "tsconfck": "^2.0.1"`
	`78`	`+ "tsconfck": "^2.0.1",`
	`79`	`+ "typedoc": "0.26.11",`
	`80`	`+ "typedoc-plugin-markdown": "4.2.10",`
	`81`	`+ "typescript": "^5.6.3"`
`79`	`82`	`}`
`80`	`83`	`}`