chore: README fixes (#634)

Author: drwpow

README.md

@@ -12,11 +12,13 @@
 
 **Features**
 
-- 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
+- ✅ [OpenAPI 3.0][openapi3]
+- ✅ [Swagger 2.0][openapi2]
+- ✅ Supports YAML and JSON schema formats
+- ✅ Supports loading via remote URL (simple authentication supported with the `--auth` flag)
+- ✅ Supports remote references: `$ref: "external.yaml#components/schemas/User"`
+- ✅ Formats using [Prettier][prettier]
+- ✅ TypeScript 4.0 features
 
 **Examples**
 
@@ -36,6 +38,7 @@ npx openapi-typescript schema.yaml --output schema.ts
 # 🚀 schema.yaml -> schema.ts [250ms]
 
 npx openapi-typescript "specs/**/*.yaml" --output schemas/
+
 # 🔭 Loading spec from specs/one.yaml…
 # 🔭 Loading spec from specs/two.yaml…
 # 🔭 Loading spec from specs/three.yaml…
@@ -71,7 +74,7 @@ import { components } from './generated-schema.ts';
 type APIResponse = components["schemas"]["APIResponse"];
 ```
 
-The reason for all the `["…"]` everywhere is because OpenAPI lets you use more characters than are valid TypeScript identifiers. The goal of this project is to generate _all_ of your schema, not merely the parts that are “TypeScript-safe.”
+Because OpenAPI schemas may have invalid TypeScript characters as names, the square brackets are a safe way to access every property.
 
 Also note that there’s a special `operations` interface that you can import `OperationObjects` by their [operationId][openapi-operationid]:
 
@@ -81,11 +84,13 @@ import { operations } from './generated-schema.ts';
 type getUsersById = operations["getUsersById"];
 ```
 
-This is the only place where our generation differs from your schema as-written, but it’s done so as a convenience and shouldn’t cause any issues (you can still use deep references as-needed).
+Even though `operations` isn’t present in your original schema, it’s a simple convenience and won’t disrupt any of your other types.
+
+_Thanks to [@gr2m](https://github.com/gr2m) for the operations feature!_
 
-_Thanks to @gr2m for the operations feature!_
+#### Outputting to stdout
 
-#### Outputting to `stdout`
+Simply omit the `--output` flag to return to stdout:
 
 ```bash
 npx openapi-typescript schema.yaml
@@ -113,21 +118,21 @@ npm i --save-dev openapi-typescript
 const fs = require("fs");
 const openapiTS = require("openapi-typescript").default;
 
-// option 1: load [object] as schema (JSON only)
+// example 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: load [string] as local file (YAML or JSON; released in v3.3)
+// example 2: load [string] as local file (YAML or JSON; released in v4.0)
 const localPath = path.join(__dirname, 'spec.yaml'); // may be YAML or JSON format
 const output = await openapiTS(localPath);
 
-// option 3: load [string] as remote URL (YAML or JSON; released in v3.3)
+// example 3: load [string] as remote URL (YAML or JSON; released in v4.0)
 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. 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.
+⚠️ As of `v4.0`, `openapiTS()` is an async function.
 
 #### Custom Formatter
 
@@ -173,7 +178,6 @@ 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