Load remote schemas

Author: drwpow

README.md

@@ -10,11 +10,15 @@
 
 🚀 Convert [OpenAPI 3.0][openapi3] and [2.0 (Swagger)][openapi2] schemas to TypeScript interfaces using Node.js.
 
-💅 The output is prettified with [Prettier][prettier] (and can be customized!).
+**Features**
 
-👉 Works for both local and remote resources (filesystem and HTTP).
+- Convert [Open API 3.x][openapi3] and [Swagger 2.x][openapi2] to TypeScript types
+- Load schemas either from local `.yaml` or `.json` files, or from a remote URL (simple authentication supported with the `--auth` flag)
+- Supports remote `$ref`s using [json-schema-ref-parser][json-schema-ref-parser]
+- Formats output using [Prettier][prettier]
+- Uses the latest TypeScript 4.0 syntax
 
-View examples:
+**Examples**
 
 - [Stripe, OpenAPI 2.0](./examples/stripe-openapi2.ts)
 - [Stripe, OpenAPI 3.0](./examples/stripe-openapi3.ts)
@@ -109,24 +113,22 @@ npm i --save-dev openapi-typescript
 const fs = require("fs");
 const openapiTS = require("openapi-typescript").default;
 
-// option 1: load JS object, write to local file
+// option 1: load [object] as schema (JSON only)
 const schema = await fs.promises.readFile("spec.json", "utf8") // must be OpenAPI JSON
 const output = await openapiTS(JSON.parse(schema));
 
-// option 2 (new in v3.3): load local path
+// option 2: load [string] as local file (YAML or JSON; released in v3.3)
 const localPath = path.join(__dirname, 'spec.yaml'); // may be YAML or JSON format
 const output = await openapiTS(localPath);
 
-// option 3 (new in v3.3): load remote URL
+// option 3: load [string] as remote URL (YAML or JSON; released in v3.3)
 const output = await openapiTS('https://myurl.com/v1/openapi.yaml');
 ```
 
-The Node API may be useful if dealing with dynamically-created schemas, or you’re using within context of a larger application. It
+The Node API may be useful if dealing with dynamically-created schemas, or you’re using within context of a larger application. Pass in either a JSON-friendly object to load a schema from memory, or a string to load a schema from a local file or remote URL (it will load the file quickly using built-in Node methods). Note that a YAML string isn’t supported in the Node.js API; either use the CLI or convert to JSON using [js-yaml][js-yaml] first.
 
 ⚠️ As of `v3.3`, this is an async function.
 
-It’s important to note that options 2 and 3 are triggered by passing in a `string` rather than an `object`.
-
 #### Custom Formatter
 
 If using the Node.js API, you can optionally pass a **formatter** to openapi-typescript. This is useful if you want to override the default types and substitute your own.
@@ -171,6 +173,7 @@ encouraged but not required.
 
 [glob]: https://www.npmjs.com/package/glob
 [js-yaml]: https://www.npmjs.com/package/js-yaml
+[json-schema-ref-parser]: https://github.com/APIDevTools/json-schema-ref-parser
 [namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
 [npm-run-all]: https://www.npmjs.com/package/npm-run-all
 [openapi-format]: https://swagger.io/specification/#data-types

bin/cli.js

@@ -69,26 +69,15 @@ function errorAndExit(errorMessage) {
 async function generateSchema(pathToSpec) {
   const output = cli.flags.output ? OUTPUT_FILE : OUTPUT_STDOUT; // FILE or STDOUT
 
-  // load spec
-  if (!cli.flags.output) {
-    output = "STDOUT"; // if --output not specified, fall back to stdout
-  }
-  if (output === "FILE") {
-    console.info(bold(`✨ openapi-typescript ${require("../package.json").version}`)); // don’t log anything to console!
-  }
-  if (cli.flags.rawSchema && !cli.flags.version) {
-    throw new Error(`--raw-schema requires --version flag`);
-  }
-
   // generate schema
   const result = await openapiTS(pathToSpec, {
-    auth: cli.flags.auth,
     additionalProperties: cli.flags.additionalProperties,
-    silent: output === "STDOUT",
-    immutableTypes: cli.flags.immutableTypes,
+    auth: cli.flags.auth,
     defaultNonNullable: cli.flags.defaultNonNullable,
+    immutableTypes: cli.flags.immutableTypes,
     prettierConfig: cli.flags.prettierConfig,
     rawSchema: cli.flags.rawSchema,
+    silent: output === OUTPUT_STDOUT,
     version: cli.flags.version,
   });
 
@@ -108,14 +97,14 @@ async function generateSchema(pathToSpec) {
     console.log(green(`🚀 ${pathToSpec} -> ${bold(outputFile)} [${time}ms]`));
   } else {
     process.stdout.write(result);
-    // (still) don’t log anything to console!
+    // if stdout, (still) don’t log anything to console!
   }
 
   return result;
 }
 
 async function main() {
-  const output = cli.flags.output ? OUTPUT_FILE : OUTPUT_STDOUT; // FILE or STDOUT
+  let output = cli.flags.output ? OUTPUT_FILE : OUTPUT_STDOUT; // FILE or STDOUT
   const pathToSpec = cli.input[0];
 
   if (output === OUTPUT_FILE) {

package-lock.json

@@ -59,15 +59,17 @@
     "kleur": "^4.1.4",
     "meow": "^9.0.0",
     "mime": "^2.5.2",
+    "node-fetch": "^2.6.1",
     "prettier": "^2.3.0",
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
     "@types/jest": "^26.0.23",
     "@types/js-yaml": "^4.0.1",
     "@types/mime": "^2.0.3",
-    "@typescript-eslint/eslint-plugin": "^4.26.0",
-    "@typescript-eslint/parser": "^4.26.0",
+    "@types/node-fetch": "^2.5.10",
+    "@typescript-eslint/eslint-plugin": "^4.25.0",
+    "@typescript-eslint/parser": "^4.25.0",
     "codecov": "^3.8.2",
     "eslint": "^7.27.0",
     "eslint-config-prettier": "^8.3.0",

package.json

@@ -1,7 +1,8 @@
 import path from "path";
+import { bold, yellow } from "kleur";
 import prettier from "prettier";
 import parserTypescript from "prettier/parser-typescript";
-import load from "./load";
+import load, { resolveSchema } from "./load";
 import { swaggerVersion } from "./utils";
 import { transformAll } from "./transform/index";
 import { GlobalContext, OpenAPI2, OpenAPI3, SchemaObject, SwaggerToTSOptions } from "./types";
@@ -16,28 +17,69 @@ export const WARNING_MESSAGE = `/**
 `;
 
 export default async function openapiTS(
-  schema: OpenAPI2 | OpenAPI3 | Record<string, SchemaObject>,
-  options: SwaggerToTSOptions = {}
+  schema: string | OpenAPI2 | OpenAPI3 | Record<string, SchemaObject>,
+  options: SwaggerToTSOptions = {} as any
 ): Promise<string> {
-  // 1. set up context
   const ctx: GlobalContext = {
     additionalProperties: options.additionalProperties || false,
     auth: options.auth,
     defaultNonNullable: options.defaultNonNullable || false,
-    formatter: typeof options.formatter === "function" ? options.formatter : undefined,
+    formatter: options && typeof options.formatter === "function" ? options.formatter : undefined,
     immutableTypes: options.immutableTypes || false,
     rawSchema: options.rawSchema || false,
-    version: options.version || swaggerVersion(schema as OpenAPI2 | OpenAPI3),
+    version: options.version || 3,
   } as any;
 
-  // 2. generate output
+  // note: we may be loading many large schemas into memory at once; take care to reuse references without cloning
+
+  // 1. load schema
+  let rootSchema: Record<string, any> = {};
+  let external: Record<string, Record<string, any>> = {};
+  if (typeof schema === "string") {
+    const schemaURL = resolveSchema(schema);
+    if (options.silent === false) console.log(yellow(`🔭 Loading spec from ${bold(schemaURL.href)}…`));
+    const schemas: Record<string, Record<string, any>> = {};
+    await load(schemaURL, {
+      ...ctx,
+      schemas,
+      rootURL: schemaURL, // as it crawls schemas recursively, it needs to know which is the root to resolve everything relative to
+    });
+    for (const k of Object.keys(schemas)) {
+      if (k === schemaURL.href) {
+        rootSchema = schemas[k];
+      } else {
+        external[k] = schemas[k];
+      }
+    }
+  } else {
+    rootSchema = schema;
+  }
+
+  // 2. generate raw output
   let output = WARNING_MESSAGE;
-  const schemaObj = await load(schema, { auth: ctx.auth, silent: options?.silent || false });
-  const rootTypes = transformAll(schemaObj, { ...ctx });
+
+  // 2a. root schema
+  if (!options?.version && !ctx.rawSchema) ctx.version = swaggerVersion(rootSchema as any); // note: root version cascades down to all subschemas
+  const rootTypes = transformAll(rootSchema, { ...ctx });
   for (const k of Object.keys(rootTypes)) {
-    if (typeof rootTypes[k] !== "string") continue;
-    output += `export interface ${k} {\n  ${rootTypes[k]}\n}\n\n`;
+    if (typeof rootTypes[k] === "string") {
+      output += `export interface ${k} {\n  ${rootTypes[k]}\n}\n\n`;
+    }
+  }
+
+  // 2b. external schemas (subschemas)
+  output += `export interface external {\n`;
+  const externalKeys = Object.keys(external);
+  externalKeys.sort((a, b) => a.localeCompare(b, "en", { numeric: true })); // sort external keys because they may have resolved in a different order each time
+  for (const subschemaURL of externalKeys) {
+    output += `  "${subschemaURL}": {\n`;
+    const subschemaTypes = transformAll(external[subschemaURL], { ...ctx, namespace: subschemaURL });
+    for (const k of Object.keys(subschemaTypes)) {
+      output += `    "${k}": {\n      ${subschemaTypes[k]}\n    }\n`;
+    }
+    output += `  }\n`;
   }
+  output += `}\n\n`;
 
   // 3. Prettify
   let prettierOptions: prettier.Options = {
@@ -46,7 +88,7 @@ export default async function openapiTS(
   };
   if (options && options.prettierConfig) {
     try {
-      const userOptions = prettier.resolveConfig.sync(path.resolve(process.cwd(), options.prettierConfig));
+      const userOptions = await prettier.resolveConfig(path.resolve(process.cwd(), options.prettierConfig));
       prettierOptions = {
         ...(userOptions || {}),
         ...prettierOptions,