Feature add custom http headers (#764)

* feat: adding nvmrc file

* feat: stronger typing with headers

* feat: adding custom http types

* test: snapshots fixing

* test: many tests failing due to indentation

* chore: remove log

* test: update test script

* fix: http headers append

* fix: further header parsing if string

* feat: allow headers and method to be sent in from CLI

* chore: cleanup prettier

* fix: cli help log for http headers

* fix: formatting

* chore: fix spacing

* test: all unit tests passing

* test: adding tests for isValidHTTPMethod

* fix: isValidHTTPMethod and parsed header to use object.entries

* chore: updating comments for index.ts

* chore: cleaning up error messages

* refactor: parseHTTPHeaders to ensure typeof object and not falsy

* feat: allow multiple headers or json headers

* feat: updating documentation for the CLI

* chore: remove nvmrc

* test: adding more utility type tests

* test: adding intersection type generation

* test: adding parse schema utility tests in load

* test: adding isFile() tests

* test: resolveSchema fully tested

* test: adding more tests to parse headers

* test: cleanup tests

* test: cleanup tests for resolveSchema, due to windows CI process throwing error

* fix: update generic for parseHttpHeader

* fix: add default primitive val

* chore: adding types

* Remove some unit tests; add CLI test for new flags

Co-authored-by: Eric Zorn <zornwebdev@gmail.com>

Author: drwpow

README.md

@@ -98,15 +98,18 @@ npx openapi-typescript schema.yaml
 
 #### CLI Options
 
-| Option                         | Alias | Default  | Description                                                                                             |
-| :----------------------------- | :---- | :------: | :------------------------------------------------------------------------------------------------------ |
-| `--output [location]`          | `-o`  | (stdout) | Where should the output file be saved?                                                                  |
-| `--auth [token]`               |       |          | (optional) Provide an auth token to be passed along in the request (only if accessing a private schema) |
-| `--immutable-types`            | `-it` | `false`  | (optional) Generates immutable types (readonly properties and readonly array)                           |
-| `--additional-properties`      | `-ap` | `false`  | (optional) Allow arbitrary properties for all schema objects without `additionalProperties: false`      |
-| `--default-non-nullable`       |       | `false`  | (optional) Treat schema objects with default values as non-nullable                                     |
-| `--prettier-config [location]` | `-c`  |          | (optional) Path to your custom Prettier configuration for output                                        |
-| `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level)                |
+| Option                         | Alias | Default  | Description                                                                                                                             |
+| :----------------------------- | :---- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `--output [location]`          | `-o`  | (stdout) | Where should the output file be saved?                                                                                                  |
+| `--auth [token]`               |       |          | (optional) Provide an auth token to be passed along in the request (only if accessing a private schema)                                 |
+| `--immutable-types`            | `-it` | `false`  | (optional) Generates immutable types (readonly properties and readonly array)                                                           |
+| `--additional-properties`      | `-ap` | `false`  | (optional) Allow arbitrary properties for all schema objects without `additionalProperties: false`                                      |
+| `--default-non-nullable`       |       | `false`  | (optional) Treat schema objects with default values as non-nullable                                                                     |
+| `--prettier-config [location]` | `-c`  |          | (optional) Path to your custom Prettier configuration for output                                                                        |
+| `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level)                                                |
+| `--httpMethod`                 | `-m`  | `GET`    | (optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL                                                         |
+| `--headersObject`              | `-h`  |          | (optional) Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over `--header`           |
+| `--header`                     | `-x`  |          | (optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the `key: value` pattern |
 
 ### 🐢 Node
 

bin/cli.js

@@ -7,14 +7,17 @@ const path = require("path");
 const glob = require("tiny-glob");
 const { default: openapiTS } = require("../dist/cjs/index.js");
 
-let cli = meow(
+const cli = meow(
   `Usage
   $ openapi-typescript [input] [options]
 
 Options
   --help                       display this
   --output, -o                 Specify output file (default: stdout)
   --auth                       (optional) Provide an authentication token for private URL
+  --headersObject, -h          (optional) Provide a JSON object as string of HTTP headers for remote schema request
+  --header, -x                 (optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern
+  --httpMethod, -m             (optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL
   --immutable-types, -it       (optional) Generates immutable types (readonly properties and readonly array)
   --additional-properties, -ap (optional) Allow arbitrary properties for all schema objects without "additionalProperties: false"
   --default-non-nullable       (optional) If a schema object has a default value set, don’t mark it as nullable
@@ -31,6 +34,20 @@ Options
       auth: {
         type: "string",
       },
+      headersObject: {
+        type: "string",
+        alias: "h",
+      },
+      header: {
+        type: "string",
+        alias: "x",
+        isMultiple: true,
+      },
+      httpMethod: {
+        type: "string",
+        alias: "m",
+        default: "GET",
+      },
       immutableTypes: {
         type: "boolean",
         alias: "it",
@@ -69,6 +86,22 @@ function errorAndExit(errorMessage) {
 async function generateSchema(pathToSpec) {
   const output = cli.flags.output ? OUTPUT_FILE : OUTPUT_STDOUT; // FILE or STDOUT
 
+  // Parse incoming headers from CLI flags
+  let httpHeaders = {};
+  // prefer --headersObject if specified
+  if (cli.flags.headersObject) {
+    httpHeaders = JSON.parse(cli.flags.headersObject); // note: this will generate a recognizable error for the user to act on
+  }
+  // otherwise, parse --header
+  else if (Array.isArray(cli.flags.header)) {
+    cli.flags.header.forEach((header) => {
+      const firstColon = header.indexOf(":");
+      const k = header.substring(0, firstColon).trim();
+      const v = header.substring(firstColon + 1).trim();
+      httpHeaders[k] = v;
+    });
+  }
+
   // generate schema
   const result = await openapiTS(pathToSpec, {
     additionalProperties: cli.flags.additionalProperties,
@@ -79,22 +112,24 @@ async function generateSchema(pathToSpec) {
     rawSchema: cli.flags.rawSchema,
     silent: output === OUTPUT_STDOUT,
     version: cli.flags.version,
+    httpHeaders,
+    httpMethod: cli.flags.httpMethod,
   });
 
   // output
   if (output === OUTPUT_FILE) {
-    let outputFile = path.resolve(process.cwd(), cli.flags.output); // note: may be directory
-    const isDir = fs.existsSync(outputFile) && fs.lstatSync(outputFile).isDirectory();
+    let outputFilePath = path.resolve(process.cwd(), cli.flags.output); // note: may be directory
+    const isDir = fs.existsSync(outputFilePath) && fs.lstatSync(outputFilePath).isDirectory();
     if (isDir) {
       const filename = pathToSpec.replace(new RegExp(`${path.extname(pathToSpec)}$`), ".ts");
-      outputFile = path.join(outputFile, filename);
+      outputFilePath = path.join(outputFilePath, filename);
     }
 
-    await fs.promises.writeFile(outputFile, result, "utf8");
+    await fs.promises.writeFile(outputFilePath, result, "utf8");
 
     const timeEnd = process.hrtime(timeStart);
     const time = timeEnd[0] + Math.round(timeEnd[1] / 1e6);
-    console.log(green(`🚀 ${pathToSpec} -> ${bold(outputFile)} [${time}ms]`));
+    console.log(green(`🚀 ${pathToSpec} -> ${bold(outputFilePath)} [${time}ms]`));
   } else {
     process.stdout.write(result);
     // if stdout, (still) don’t log anything to console!

package-lock.json

@@ -50,7 +50,10 @@
     "prepare": "npm run build",
     "pregenerate": "npm run build",
     "test": "npm run build && jest --no-cache",
+    "test:watch": "npm run build && jest --no-cache --watch",
+    "test:update": "npm run build && jest --no-cache --u",
     "test:coverage": "npm run build && jest --no-cache --coverage && codecov",
+    "test:coverage:local": "npm run build && jest --no-cache --collectCoverage",
     "typecheck": "tsc --noEmit --project tsconfig.esm.json",
     "version": "npm run build"
   },
@@ -66,7 +69,7 @@
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
-    "@types/jest": "^27.0.0",
+    "@types/jest": "^27.0.2",
     "@types/js-yaml": "^4.0.1",
     "@types/mime": "^2.0.3",
     "@types/node-fetch": "^2.5.12",

package.json

@@ -17,9 +17,22 @@ export const WARNING_MESSAGE = `/**
 
 `;
 
-export default async function openapiTS(
+/**
+ * This function is the entry to the program and allows the user to pass in a remote schema and/or local schema.
+ * The URL or schema and headers can be passed in either programtically and/or via the CLI.
+ * Remote schemas are fetched from a server that supplies JSON or YAML format via an HTTP GET request. File based schemas
+ * are loaded in via file path, most commonly prefixed with the file:// format. Alternatively, the user can pass in
+ * OpenAPI2 or OpenAPI3 schema objects that can be parsed directly by the function without reading the file system.
+ *
+ * Function overloading is utilized for generating stronger types for our different schema types and option types.
+ *
+ * @param {string} schema Root Swagger Schema HTTP URL, File URL, and/or JSON or YAML schema
+ * @param {SwaggerToTSOptions<typeof schema>} [options] Options to specify to the parsing system
+ * @return {Promise<string>}  {Promise<string>} Parsed file schema
+ */
+async function openapiTS(
   schema: string | OpenAPI2 | OpenAPI3 | Record<string, SchemaObject>,
-  options: SwaggerToTSOptions = {} as any
+  options: SwaggerToTSOptions = {} as Partial<SwaggerToTSOptions>
 ): Promise<string> {
   const ctx: GlobalContext = {
     additionalProperties: options.additionalProperties || false,
@@ -40,11 +53,15 @@ export default async function openapiTS(
   if (typeof schema === "string") {
     const schemaURL = resolveSchema(schema);
     if (options.silent === false) console.log(yellow(`🔭 Loading spec from ${bold(schemaURL.href)}…`));
+
     await load(schemaURL, {
       ...ctx,
       schemas: allSchemas,
       rootURL: schemaURL, // as it crawls schemas recursively, it needs to know which is the root to resolve everything relative to
+      httpHeaders: options.httpHeaders,
+      httpMethod: options.httpMethod,
     });
+
     for (const k of Object.keys(allSchemas)) {
       if (k === schemaURL.href) {
         rootSchema = allSchemas[k];
@@ -53,7 +70,14 @@ export default async function openapiTS(
       }
     }
   } else {
-    await load(schema, { ...ctx, schemas: allSchemas, rootURL: new URL(VIRTUAL_JSON_URL) });
+    await load(schema, {
+      ...ctx,
+      schemas: allSchemas,
+      rootURL: new URL(VIRTUAL_JSON_URL),
+      httpHeaders: options.httpHeaders,
+      httpMethod: options.httpMethod,
+    });
+
     for (const k of Object.keys(allSchemas)) {
       if (k === VIRTUAL_JSON_URL) {
         rootSchema = allSchemas[k];
@@ -108,3 +132,5 @@ export default async function openapiTS(
   }
   return prettier.format(output, prettierOptions);
 }
+
+export default openapiTS;

src/index.ts

@@ -5,7 +5,8 @@ import { URL } from "url";
 import slash from "slash";
 import mime from "mime";
 import yaml from "js-yaml";
-import { GlobalContext } from "./types";
+import { red } from "kleur";
+import { GlobalContext, Headers } from "./types";
 import { parseRef } from "./utils";
 
 type PartialSchema = Record<string, any>; // not a very accurate type, but this is easier to deal with before we know we’re dealing with a valid spec
@@ -43,17 +44,52 @@ export function resolveSchema(url: string): URL {
   const localPath = path.isAbsolute(url)
     ? new URL("", `file://${slash(url)}`)
     : new URL(url, `file://${slash(process.cwd())}/`); // if absolute path is provided use that; otherwise search cwd\
+
   if (!fs.existsSync(localPath)) {
     throw new Error(`Could not locate ${url}`);
   } else if (fs.statSync(localPath).isDirectory()) {
     throw new Error(`${localPath} is a directory not a file`);
   }
+
   return localPath;
 }
 
+/**
+ * Accepts income HTTP headers and appends them to
+ * the fetch request for the schema.
+ *
+ * @param {HTTPHeaderMap} httpHeaders
+ * @return {Record<string, string>}  {Record<string, string>} Final HTTP headers outcome.
+ */
+function parseHttpHeaders(httpHeaders: Record<string, any>): Headers {
+  const finalHeaders: Record<string, string> = {};
+
+  // Obtain the header key
+  for (const [k, v] of Object.entries(httpHeaders)) {
+    // If the value of the header is already a string, we can move on, otherwise we have to parse it
+    if (typeof v === "string") {
+      finalHeaders[k] = v;
+    } else {
+      try {
+        const stringVal = JSON.stringify(v);
+        finalHeaders[k] = stringVal;
+      } catch (err) {
+        /* istanbul ignore next */
+        console.error(
+          red(`Cannot parse key: ${k} into JSON format. Continuing with the next HTTP header that is specified`)
+        );
+      }
+    }
+  }
+
+  return finalHeaders;
+}
+
 interface LoadOptions extends GlobalContext {
   rootURL: URL;
   schemas: SchemaMap;
+  httpHeaders?: Headers;
+  httpMethod?: string;
 }
 
 // temporary cache for load()
@@ -65,7 +101,7 @@ export default async function load(
   options: LoadOptions
 ): Promise<{ [url: string]: PartialSchema }> {
   const isJSON = schema instanceof URL === false; // if this is dynamically-passed-in JSON, we’ll have to change a few things
-  let schemaID = isJSON ? new URL(VIRTUAL_JSON_URL).href : schema.href;
+  let schemaID = isJSON ? new URL(VIRTUAL_JSON_URL).href : (schema.href as string);
 
   const schemas = options.schemas;
 
@@ -88,13 +124,20 @@ export default async function load(
       contentType = mime.getType(schemaID) || "";
     } else {
       // load remote
-      const res = await fetch(schemaID, {
-        method: "GET",
-        headers: {
-          "User-Agent": "openapi-typescript",
-          ...(options.auth ? {} : { Authorization: options.auth }),
-        },
-      });
+      const headers: Headers = {
+        "User-Agent": "openapi-typescript",
+      };
+      if (options.auth) headers.Authorizaton = options.auth;
+
+      // Add custom parsed HTTP headers
+      if (options.httpHeaders) {
+        const parsedHeaders = parseHttpHeaders(options.httpHeaders);
+        for (const [k, v] of Object.entries(parsedHeaders)) {
+          headers[k] = v;
+        }
+      }
+
+      const res = await fetch(schemaID, { method: options.httpMethod || "GET", headers });
       contentType = res.headers.get("Content-Type") || "";
       contents = await res.text();
     }

src/load.ts

@@ -21,6 +21,8 @@ export interface OpenAPI3 {
   };
 }
 
+export type Headers = Record<string, string>;
+
 export interface HeaderObject {
   // note: this extends ParameterObject, minus "name" & "in"
   type?: string; // required
@@ -134,6 +136,21 @@ export interface SwaggerToTSOptions {
   silent?: boolean;
   /** (optional) OpenAPI version. Must be present if parsing raw schema */
   version?: number;
+  /**
+   * (optional) List of HTTP headers that will be sent with the fetch request to a remote schema. This is
+   * in addition to the authorization header. In some cases, servers require headers such as Accept: application/json
+   * or Accept: text/yaml to be sent in order to figure out how to properly fetch the OpenAPI/Swagger document as code.
+   * These headers will only be sent in the case that the schema URL protocol is of type http or https.
+   */
+  httpHeaders?: Headers;
+  /**
+   * HTTP verb used to fetch the schema from a remote server. This is only applied
+   * when the schema is a string and has the http or https protocol present. By default,
+   * the request will use the HTTP GET method to fetch the schema from the server.
+   *
+   * @default {string} GET
+   */
+  httpMethod?: string;
 }
 
 /** Context passed to all submodules */