Merge pull request #3 from moznion/default_header

Support default header

Author: moznion

.gitignore

@@ -1,4 +1,4 @@
 node_modules/
 dist/
-src/test_resources/generated_client.ts
+src/test_resources/generated_client*.ts
 

README.md

@@ -30,18 +30,21 @@ npx openapi-fetch-gen --input ./schema.d.ts --output ./client.ts
 
 Options:
 
-- `-V, --version        output the version number`
-- `-i, --input <path>   path to input OpenAPI TypeScript definition file`
-- `-o, --output <path>  path to output generated client file (default: "./client.ts")`
-- `-h, --help           display help for command`
+```
+  -V, --version                                         output the version number
+  -i, --input <path>                                    path to input OpenAPI TypeScript definition file
+  -o, --output <path>                                   path to output generated client file (default: "./client.ts")
+  --default-headers <comma_separated_names_of_headers>  header names so that the generated client includes the default HTTP headers across all endpoints (default: "")
+  -h, --help                                            display help for command
+```
 
-## Example
+### Example
 
-Please refer the [examples](./examples/).
+Please refer to the [examples](./examples/).
 
 `schema.d.ts` is generated from `schema.yaml` by `openapi-typescript`, and `generated_client.ts` is generated by this tool according to the `schema.d.ts`.
 
-FYI, the client user would be able to use it as like the following:
+FYI, you can use the generated client as follows:
 
 ```typescript
 import { Client } from "./generated_client";
@@ -62,6 +65,133 @@ async function doSomething() {
 }
 ```
 
+### Default HTTP Headers
+
+This tool provides a `--default-headers` CLI option to configure the generated client to use default HTTP headers.
+
+For example, when you specify:
+
+```bash
+npx openapi-fetch-gen \
+  --input ./schema.d.ts \
+  --output ./client.ts \
+  --default-headers "Authorization, Application-Version"
+```
+
+the `Client` constructor accepts those default values:
+
+```typescript
+type DefaultHeaders = Record<'Authorization' | 'Application-Version', string>;
+
+export class Client {
+  constructor(clientOptions: ClientOptions, defaultHeaders: DefaultHeaders) { ... }
+}
+```
+
+Endpoint methods that require those headers no longer need the default values to be passed explicitly.
+
+For example, given this schema:
+
+```typescript
+"/users/bulk/{jobId}": {
+  get: {
+    parameters: {
+      query?: never;
+      header: {
+        /** @description Authorization Header */
+        Authorization: string;
+        /** @description Application version */
+        "Application-Version": string;
+        /** @description Identifier of something */
+        "Something-Id": string;
+      };
+      path: {
+        /** @description Bulk import job identifier */
+        jobId: string;
+      };
+      cookie?: never;
+    };
+```
+
+When `--default-headers` is not specified, the generated client method looks like this:
+
+```typescript
+async getUsersBulkJobid(params: {
+  header: {
+    Authorization: string;
+    "Application-Version": string;
+    "Something-Id": string;
+  };
+  path: { jobId: string };
+}) {
+  ...
+}
+```
+
+This requires you to pass all header values explicitly.
+
+When you do specify `--default-headers`, the signature becomes:
+
+```typescript
+async getUsersBulkJobid(
+  params: keyof Omit<
+    {
+      Authorization: string;
+      "Application-Version": string;
+      "Something-Id": string;
+    },
+    keyof DefaultHeaders
+  > extends never
+    ? {
+        header?: {
+          Authorization: string;
+          "Application-Version": string;
+          "Something-Id": string;
+        };
+        path: { jobId: string };
+      }
+    : {
+        header:
+          | Omit<
+              {
+                Authorization: string;
+                "Application-Version": string;
+                "Something-Id": string;
+              },
+              keyof DefaultHeaders
+            >
+          | {
+              Authorization: string;
+              "Application-Version": string;
+              "Something-Id": string;
+            };
+        path: { jobId: string };
+      },
+) {
+  ...
+}
+```
+
+That signature means you can:
+
+- **Omit** the defaulted headers and only pass additional ones (here, `Something-Id`):
+
+```typescript
+client.getUsersBulkJobid({header: {"Something-Id": "foobar"}, path: {jobId: "123"}});
+```
+
+- **Override** all headers, including the defaults:
+
+```typescript
+client.getUsersBulkJobid({header: {"Authorization": "foo", "Application-Version": "bar", "Something-Id": "foobar"}, path: {jobId: "123"}});
+```
+
+If your default headers cover **all** required headers for the endpoint (e.g. `--default-headers 'Authorization, Application-Version, Something-Id'`), you can omit the `header` parameter entirely:
+
+```typescript
+client.getUsersBulkJobid({path: {jobId: "123"}});
+```
+
 ## License
 
 MIT

package.json

@@ -17,8 +17,9 @@
     "build": "pnpm clean && tsc",
     "lint": "biome check src",
     "fix": "biome check --write src",
-    "test": "vitest run",
+    "test": "pnpm test:clean && vitest run",
     "test:watch": "vitest",
+    "test:clean": "rm -f ./src/test_resources/generated_client*",
     "generate_test_resource": "openapi-typescript -o ./src/test_resources/schema.d.ts ./src/test_resources/schema.yaml"
   },
   "bin": {

pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+ignoredBuiltDependencies:
+  - esbuild
+
+onlyBuiltDependencies:
+  - '@biomejs/biome'

src/cli.ts

@@ -23,20 +23,31 @@ program
     "path to output generated client file",
     "./client.ts",
   )
+  .option(
+    "--default-headers <comma_separated_names_of_headers>",
+    "header names so that the generated client includes the default HTTP headers across all endpoints",
+    "",
+  )
   .parse(process.argv);
 
 const options = program.opts();
 
 try {
   const inputPath = path.resolve(options["input"]);
   const outputPath = path.resolve(options["output"]);
+  const defaultHeaderNamesString = options["defaultHeaders"] as string;
 
   if (!fs.existsSync(inputPath)) {
     console.error(`Error: Input file not found: ${inputPath}`);
     process.exit(1);
   }
 
-  const clientCode = generateClient(inputPath);
+  const defaultHeaderNames = defaultHeaderNamesString
+    .split(",")
+    .map((h) => h.trim())
+    .filter((h) => h !== "");
+
+  const clientCode = generateClient(inputPath, defaultHeaderNames);
 
   fs.writeFileSync(outputPath, clientCode);
   console.log(`Successfully generated client at: ${outputPath}`);

src/index.ts

@@ -15,7 +15,10 @@ import {
  * Generates a TypeScript API client using openapi-fetch based on TypeScript interface definitions
  * generated by openapi-typescript.
  */
-export function generateClient(schemaFilePath: string): string {
+export function generateClient(
+  schemaFilePath: string,
+  defaultHeaderNames: string[],
+): string {
   const project = new Project({
     compilerOptions: {
       target: ScriptTarget.Latest,
@@ -29,7 +32,11 @@ export function generateClient(schemaFilePath: string): string {
     throw new Error(`Interface "paths" not found in ${schemaFilePath}`);
   }
 
-  return generateClientCode(pathsInterface, path.basename(schemaFilePath));
+  return generateClientCode(
+    pathsInterface,
+    path.basename(schemaFilePath),
+    defaultHeaderNames,
+  );
 }
 
 function findInterface(
@@ -46,15 +53,23 @@ interface EndpointInfo {
   commentLines: string[];
   paramsType: string | null;
   bodyType: string | null;
+  headerExists: boolean;
 }
 
 function generateClientCode(
   pathsInterface: InterfaceDeclaration,
   schemaFileName: string,
+  defaultHeaderNames: string[],
 ): string {
-  const endpoints = extractEndpointsInfo(pathsInterface);
+  const defaultHeaderExists = defaultHeaderNames.length > 0;
+
+  const endpoints = extractEndpointsInfo(pathsInterface, defaultHeaderExists);
 
-  const clientClass = generateClientClass(endpoints);
+  const defaultHeaderType =
+    defaultHeaderNames.length > 0
+      ? `type DefaultHeaders = Record<${defaultHeaderNames.map((n) => `"${n}"`).join("|")}, string>\n`
+      : "";
+  const clientClass = generateClientClass(endpoints, defaultHeaderExists);
 
   const code = [
     "// THIS FILE IS AUTO-GENERATED BY openapi-fetch-gen.",
@@ -63,6 +78,7 @@ function generateClientCode(
     `import createClient, { type ClientOptions } from "openapi-fetch";`,
     `import type { paths } from "./${schemaFileName.replace(/\.d\.ts$/, "")}"; // generated by openapi-typescript`,
     "",
+    defaultHeaderType,
     clientClass,
   ].join("\n");
 
@@ -74,6 +90,7 @@ function generateClientCode(
 
 function extractEndpointsInfo(
   pathsInterface: InterfaceDeclaration,
+  defaultHeaderExists: boolean,
 ): EndpointInfo[] {
   const endpoints: EndpointInfo[] = [];
 
@@ -121,16 +138,41 @@ function extractEndpointsInfo(
         .getProperties()
         .map((prop) => {
           const propType = prop.getTypeAtLocation(decl);
-          const typeText = propType.getText();
-          if (typeText === "never") {
-            return "";
+          const text = propType.getText();
+          const name = prop.getName();
+          if (text === "never") {
+            return { name, text: "" };
           }
-          return `${prop.getName()}: ${typeText}`;
+          return { name, text };
         })
-        .filter((typeText) => typeText !== "")
-        .join(", ");
-      if (paramTypes !== "") {
-        paramsType = `{${paramTypes}}`;
+        .filter((kv) => kv["text"] !== "");
+
+      const headerType = paramTypes.find((kv) => kv.name === "header");
+      if (defaultHeaderExists && headerType) {
+        const nonHeaderParams = paramTypes
+          .filter((kv) => kv.name !== "header")
+          .map((kv) => `${kv.name}: ${kv.text}`)
+          .join("\n");
+
+        paramsType = `keyof Omit<${headerType["text"]}, keyof DefaultHeaders> extends never ?
+  {
+    header?: ${headerType["text"]},
+    ${nonHeaderParams}
+  } :
+  {
+    header:
+      | Omit<${headerType["text"]}, keyof DefaultHeaders>
+      | ${headerType["text"]},
+    ${nonHeaderParams}
+}
+`;
+      } else {
+        const params = paramTypes
+          .map((kv) => `${kv.name}: ${kv.text}`)
+          .join("\n");
+        if (params !== "") {
+          paramsType = `{${params}}`;
+        }
       }
 
       const requestBodyProp = decl.getType().getProperty("requestBody");
@@ -185,22 +227,28 @@ function extractEndpointsInfo(
         commentLines,
         paramsType,
         bodyType: requestBodyType,
+        headerExists: headerType !== undefined,
       });
     }
   }
 
   return endpoints;
 }
 
-function generateClientClass(endpoints: EndpointInfo[]): string {
+function generateClientClass(
+  endpoints: EndpointInfo[],
+  defaultHeaderExists: boolean,
+): string {
   const classCode = [
-    "export class Client {",
-    "    private readonly client;",
-    "",
-    "    constructor(clientOptions: ClientOptions) {",
-    "        this.client = createClient<paths>(clientOptions);",
-    "    }",
-    "",
+    `export class Client {
+       private readonly client;
+       ${defaultHeaderExists ? "private readonly defaultHeaders: DefaultHeaders;" : ""}
+
+       constructor(clientOptions: ClientOptions${defaultHeaderExists ? ", defaultHeaders: DefaultHeaders" : ""}) {
+         this.client = createClient<paths>(clientOptions);
+         ${defaultHeaderExists ? "this.defaultHeaders = defaultHeaders;" : ""}
+       }
+    `,
   ];
 
   // Generate class methods for each endpoint
@@ -249,7 +297,14 @@ function generateClientClass(endpoints: EndpointInfo[]): string {
     );
 
     if (paramsType) {
-      classCode.push("            params,");
+      if (defaultHeaderExists && endpoint.headerExists) {
+        classCode.push(`params: {
+  ...params,
+  header: {...this.defaultHeaders, ...params.header},
+},`);
+      } else {
+        classCode.push("params,");
+      }
     }
 
     if (bodyType) {