From e172cce360b882bfa41a16da5c0ddffc01f848d8 Mon Sep 17 00:00:00 2001
From: Chris Armstrong <chris-armstrong@noreply.users.github.com>
Date: Fri, 19 Feb 2021 10:44:30 +1100
Subject: [PATCH] expand README to include information about external reference
 support

---
 README.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 824c675e3..c01e3440c 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@
 - Supports JSON and YAML files for input
 - Supports generation through CLI, Node.js and NPX
 - Supports tsc and @babel/plugin-transform-typescript
-
+- Supports external references using [`json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser/)
 
 ## Install
 
@@ -392,6 +392,32 @@ const getToken = async () => {
 OpenAPI.TOKEN = getToken;
 ```
 
+### References
+
+Local references to schema definitions (those beginning with `#/definitions/schemas/`) will
+be converted to type references to the equivalent, generated top-level type.
+
+The OpenAPI generator also supports external references, which allows you to break
+down your openapi.yml into multiple sub-files, or incorporate third-party schemas
+as part of your types to ensure everything is able to be TypeScript generated.
+
+External references may be:
+* *relative references* - references to other files at the same location e.g.
+    `{ $ref: 'schemas/customer.yml' }`
+* *remote references* - fully qualified references to another remote location
+     e.g. `{ $ref: 'https://myexampledomain.com/schemas/customer_schema.yml' }`
+
+    For remote references, both files (when the file is on the current filesystem)
+    and http(s) URLs are supported.
+
+External references may also contain internal paths in the external schema (e.g.
+`schemas/collection.yml#/definitions/schemas/Customer`) and back-references to
+the base openapi file or between files (so that you can reference another
+schema in the main file as a type of an object or array property, for example).
+
+At start-up, an OpenAPI or Swagger file with external references will be "bundled",
+so that all external references and back-references will be resolved (but local
+references preserved).
 
 ### Compare to other generators
 Depending on which swagger generator you use, you will see different output.