Load remote schemas

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)
@@ -125,24 +129,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.
@@ -187,6 +189,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

@@ -67,28 +67,10 @@ async function main() {
     throw new Error(`--raw-schema requires --version flag`);
   }
 
-<<<<<<< HEAD
-  // 1. input
-  let spec = undefined;
-  try {
-    spec = await loadSpec(pathToSpec, {
-      auth: cli.flags.auth,
-      log: output !== "STDOUT",
-    });
-  } catch (err) {
-    process.exitCode = 1; // needed for async functions
-    throw new Error(red(`❌ ${err}`));
-  }
-
-  // 2. generate schema (the main part!)
-  const result = openapiTS(spec, {
-    auth: cli.flags.auth,
-    additionalProperties: cli.flags.additionalProperties,
-=======
   const result = await openapiTS(pathToSpec, {
     auth: cli.flags.auth,
+    additionalProperties: cli.flags.additionalProperties,
     silent: output === "STDOUT",
->>>>>>> 3ea8d8f (Absorb schema loading/parsing into Node API)
     immutableTypes: cli.flags.immutableTypes,
     prettierConfig: cli.flags.prettierConfig,
     rawSchema: cli.flags.rawSchema,