Merge pull request #349 from OpenAPI-Qraft/feat/default-error-resolving

radist2s · web-flow · commit 949b8acebad6 · 2025-06-21T15:51:24.000+04:00
feat(plugin): add support for responses with `$ref` specification
diff --git a/.changeset/true-weeks-love.md b/.changeset/true-weeks-love.md
@@ -0,0 +1,6 @@
+---
+'@openapi-qraft/test-fixtures': patch
+'@openapi-qraft/plugin': patch
+---
+
+Add support for responses with `$ref` specification.
diff --git a/packages/openapi-typescript-plugin/src/__snapshots__/no-extra-options.ts.snapshot.ts b/packages/openapi-typescript-plugin/src/__snapshots__/no-extra-options.ts.snapshot.ts
@@ -174,7 +174,17 @@ export interface components {
             url: string;
         };
     };
-    responses: never;
+    responses: {
+        /** @description Unexpected error */
+        DefaultErrorSchemaResponse: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorSchemaResponse"];
+            };
+        };
+    };
     parameters: {
         IdIn: string[];
         /** @example 2023-06-04 */
@@ -262,15 +272,7 @@ export interface operations {
                     "application/json": components["schemas"]["HTTPValidationError"];
                 };
             };
-            /** @description Unexpected error */
-            default: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorSchemaResponse"];
-                };
-            };
+            default: components["responses"]["DefaultErrorSchemaResponse"];
         };
     };
     get_approval_policies_id: {
@@ -514,15 +516,7 @@ export interface operations {
                     "application/json": components["schemas"]["HTTPValidationError"];
                 };
             };
-            /** @description Internal Server Error */
-            default: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorSchemaResponse"];
-                };
-            };
+            default: components["responses"]["DefaultErrorSchemaResponse"];
         };
     };
     post_files: {
diff --git a/packages/openapi-typescript-plugin/src/__snapshots__/with-explicit-component-enum-exports.ts.snapshot.ts b/packages/openapi-typescript-plugin/src/__snapshots__/with-explicit-component-enum-exports.ts.snapshot.ts
@@ -89,7 +89,17 @@ export interface components {
             url: string;
         };
     };
-    responses: never;
+    responses: {
+        /** @description Unexpected error */
+        DefaultErrorSchemaResponse: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorSchemaResponse"];
+            };
+        };
+    };
     parameters: {
         IdIn: string[];
         /** @example 2023-06-04 */
@@ -160,15 +170,7 @@ export interface operations {
                     "application/json": components["schemas"]["HTTPValidationError"];
                 };
             };
-            /** @description Internal Server Error */
-            default: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorSchemaResponse"];
-                };
-            };
+            default: components["responses"]["DefaultErrorSchemaResponse"];
         };
     };
     post_files: {
diff --git a/packages/openapi-typescript-plugin/src/__snapshots__/with-explicit-component-exports.ts.snapshot.ts b/packages/openapi-typescript-plugin/src/__snapshots__/with-explicit-component-exports.ts.snapshot.ts
@@ -89,7 +89,17 @@ export interface components {
             url: string;
         };
     };
-    responses: never;
+    responses: {
+        /** @description Unexpected error */
+        DefaultErrorSchemaResponse: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorSchemaResponse"];
+            };
+        };
+    };
     parameters: {
         IdIn: string[];
         /** @example 2023-06-04 */
@@ -160,15 +170,7 @@ export interface operations {
                     "application/json": components["schemas"]["HTTPValidationError"];
                 };
             };
-            /** @description Internal Server Error */
-            default: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorSchemaResponse"];
-                };
-            };
+            default: components["responses"]["DefaultErrorSchemaResponse"];
         };
     };
     post_files: {
diff --git a/packages/openapi-typescript-plugin/src/__snapshots__/with-extra-options.ts.snapshot.ts b/packages/openapi-typescript-plugin/src/__snapshots__/with-extra-options.ts.snapshot.ts
@@ -126,7 +126,17 @@ export interface components {
             url: string;
         };
     };
-    responses: never;
+    responses: {
+        /** @description Unexpected error */
+        DefaultErrorSchemaResponse: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorSchemaResponse"];
+            };
+        };
+    };
     parameters: {
         IdIn: string[];
         /** @example 2023-06-04 */
@@ -197,15 +207,7 @@ export interface operations {
                     "application/json": components["schemas"]["HTTPValidationError"];
                 };
             };
-            /** @description Internal Server Error */
-            default: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorSchemaResponse"];
-                };
-            };
+            default: components["responses"]["DefaultErrorSchemaResponse"];
         };
     };
     post_files: {
diff --git a/packages/plugin/src/lib/open-api/OpenAPISchemaType.ts b/packages/plugin/src/lib/open-api/OpenAPISchemaType.ts
@@ -24,7 +24,8 @@ export type OpenAPISchemaType = {
         };
         responses: {
           [statusCode in number | 'default']: {
-            description: string;
+            $ref?: string;
+            description?: string;
             content?: {
               [contentType: string]:
                 | {
diff --git a/packages/plugin/src/lib/open-api/getServices.ts b/packages/plugin/src/lib/open-api/getServices.ts
@@ -66,6 +66,13 @@ export const getServices = (
         >
       >(
         (acc, [statusCode, response]) => {
+          if (response.$ref) {
+            response = resolveDocumentLocalRef(
+              response.$ref,
+              openApiJson
+            ) as typeof response;
+          }
+
           const statusType =
             statusCode !== 'default' && // See "default" response https://swagger.io/docs/specification/describing-responses/#default
             Number(statusCode) < 400
diff --git a/packages/test-fixtures/openapi.json b/packages/test-fixtures/openapi.json
@@ -120,12 +120,7 @@
             }
           },
           "default": {
-            "description": "Unexpected error",
-            "content": {
-              "application/json": {
-                "schema": { "$ref": "#/components/schemas/ErrorSchemaResponse" }
-              }
-            }
+            "$ref": "#/components/responses/DefaultErrorSchemaResponse"
           }
         },
         "security": [{ "userToken": [] }, { "partnerToken": [] }]
@@ -493,12 +488,7 @@
             }
           },
           "default": {
-            "description": "Internal Server Error",
-            "content": {
-              "application/json": {
-                "schema": { "$ref": "#/components/schemas/ErrorSchemaResponse" }
-              }
-            }
+            "$ref": "#/components/responses/DefaultErrorSchemaResponse"
           }
         },
         "security": [{ "HTTPBearer": [] }]
@@ -881,6 +871,16 @@
           }
         }
       }
+    },
+    "responses": {
+      "DefaultErrorSchemaResponse": {
+        "description": "Unexpected error",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorSchemaResponse" }
+          }
+        }
+      }
     }
   }
 }

Original file line number	Diff line number	Diff line change
`@@ -120,12 +120,7 @@`
`120`	`120`	`}`
`121`	`121`	`},`
`122`	`122`	`"default": {`
`123`		`- "description": "Unexpected error",`
`124`		`- "content": {`
`125`		`- "application/json": {`
`126`		`- "schema": { "$ref": "#/components/schemas/ErrorSchemaResponse" }`
`127`		`- }`
`128`		`- }`
	`123`	`+ "$ref": "#/components/responses/DefaultErrorSchemaResponse"`
`129`	`124`	`}`
`130`	`125`	`},`
`131`	`126`	`"security": [{ "userToken": [] }, { "partnerToken": [] }]`
`@@ -493,12 +488,7 @@`
`493`	`488`	`}`
`494`	`489`	`},`
`495`	`490`	`"default": {`
`496`		`- "description": "Internal Server Error",`
`497`		`- "content": {`
`498`		`- "application/json": {`
`499`		`- "schema": { "$ref": "#/components/schemas/ErrorSchemaResponse" }`
`500`		`- }`
`501`		`- }`
	`491`	`+ "$ref": "#/components/responses/DefaultErrorSchemaResponse"`
`502`	`492`	`}`
`503`	`493`	`},`
`504`	`494`	`"security": [{ "HTTPBearer": [] }]`
`@@ -881,6 +871,16 @@`
`881`	`871`	`}`
`882`	`872`	`}`
`883`	`873`	`}`
	`874`	`+ },`
	`875`	`+ "responses": {`
	`876`	`+ "DefaultErrorSchemaResponse": {`
	`877`	`+ "description": "Unexpected error",`
	`878`	`+ "content": {`
	`879`	`+ "application/json": {`
	`880`	`+ "schema": { "$ref": "#/components/schemas/ErrorSchemaResponse" }`
	`881`	`+ }`
	`882`	`+ }`
	`883`	`+ }`
`884`	`884`	`}`
`885`	`885`	`}`
`886`	`886`	`}`