Support JSONSchema $defs (#1317)

* Support JSONSchema $defs

* Add JSONSchema $defs docs

* Add robots.txt

* Docs update

Author: drwpow

.changeset/config.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
   "changelog": ["@changesets/changelog-github", { "repo": "drwpow/openapi-typescript" }],
-  "ignore": ["openapi-typescript-docs"],
+  "ignore": ["openapi-typescript-docs", "@example/*"],
   "commit": false,
   "fixed": [],
   "linked": [],

.changeset/kind-ladybugs-kneel.md

@@ -0,0 +1,5 @@
+---
+"openapi-typescript": patch
+---
+
+Fix JSONSchema $defs

.changeset/sour-ants-walk.md

@@ -0,0 +1,5 @@
+---
+"openapi-typescript": patch
+---
+
+Improve remote $ref parsing

docs/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /

docs/src/content/docs/advanced.md

@@ -351,3 +351,70 @@ prefixItems:
 
   </tbody>
 </table>
+
+### Use `$defs` only in objects
+
+<a href="https://json-schema.org/understanding-json-schema/structuring.html#defs" target="_blank" rel="noopener noreferrer">JSONSchema $defs</a> can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:
+
+```yaml
+components:
+  schemas:
+    DefType:
+      type: object # ✅ `type: "object"` is OK to define $defs on
+      $defs:
+        myDefType:
+          type: string
+    MyType:
+      type: object
+      properties:
+        myType:
+          $ref: "#/components/schemas/DefType/$defs/myDefType"
+```
+
+This will transform into the following TypeScript:
+
+```ts
+export interface components {
+  schemas: {
+    DefType: {
+      $defs: {
+        myDefType: string;
+      };
+    };
+    MyType: {
+      myType?: components["schemas"]["DefType"]["$defs"]["myDefType"]; // ✅ Works
+    };
+  };
+}
+```
+
+However, this won’t:
+
+```yaml
+components:
+  schemas:
+    DefType:
+      type: string # ❌ this won’t keep its $defs
+      $defs:
+        myDefType:
+          type: string
+    MyType:
+      properties:
+        myType:
+          $ref: "#/components/schemas/DefType/$defs/myDefType"
+```
+
+Because it will transform into:
+
+```ts
+export interface components {
+  schemas: {
+    DefType: string;
+    MyType: {
+      myType?: components["schemas"]["DefType"]["$defs"]["myDefType"]; // ❌ Property '$defs' does not exist on type 'String'.
+    };
+  };
+}
+```
+
+So be wary about where you define `$defs` as they may go missing in your final generated types. When in doubt, you can always define `$defs` at the root schema level.

packages/openapi-fetch/examples/nextjs/lib/api/v1.d.ts

@@ -98,6 +98,8 @@ export interface components {
   pathItems: never;
 }
 
+export type $defs = Record<string, never>;
+
 export type external = Record<string, never>;
 
 export interface operations {

packages/openapi-fetch/examples/react-query/src/lib/api/v1.d.ts

@@ -98,6 +98,8 @@ export interface components {
   pathItems: never;
 }
 
+export type $defs = Record<string, never>;
+
 export type external = Record<string, never>;
 
 export interface operations {

packages/openapi-fetch/examples/sveltekit/src/lib/api/v1.d.ts

@@ -98,6 +98,8 @@ export interface components {
   pathItems: never;
 }
 
+export type $defs = Record<string, never>;
+
 export type external = Record<string, never>;
 
 export interface operations {

packages/openapi-fetch/test/v1.d.ts

@@ -422,6 +422,8 @@ export interface components {
   pathItems: never;
 }
 
+export type $defs = Record<string, never>;
+
 export type external = Record<string, never>;
 
 export interface operations {