swagger-schema-official: add support for references in parameters and responses (#29532)

* add support for references in parameters and responses

* update definitions by section

* expand scope to schema references

types/swagger-schema-official/index.d.ts

@@ -1,6 +1,6 @@
 // Type definitions for swagger-schema-official 2.0
 // Project: http://swagger.io/specification/
-// Definitions by: Mohsen Azimi <https://github.com/mohsen1>, Ben Southgate <https://github.com/bsouthga>, Nicholas Merritt <https://github.com/nimerritt>
+// Definitions by: Mohsen Azimi <https://github.com/mohsen1>, Ben Southgate <https://github.com/bsouthga>, Nicholas Merritt <https://github.com/nimerritt>, Mauri Edo <https://github.com/mauriedo>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
 export interface Info {
@@ -47,7 +47,7 @@ export interface BaseParameter {
 }
 
 export interface BodyParameter extends BaseParameter {
-  schema?: Schema;
+  schema?: Referenceable<Schema>;
 }
 
 export interface QueryParameter extends BaseParameter, BaseSchema {
@@ -87,29 +87,32 @@ export interface Path {
   options?: Operation;
   head?: Operation;
   patch?: Operation;
-  parameters?: Parameter[];
+  parameters?: Array<Referenceable<Parameter>>;
 }
 
 // ----------------------------- Operation -----------------------------------
 export interface Operation {
-  responses: { [responseName: string]: Response };
+  responses: { [responseName: string]: Referenceable<Response>};
   summary?: string;
   description?: string;
   externalDocs?: ExternalDocs;
   operationId?: string;
   produces?: string[];
   consumes?: string[];
-  parameters?: Parameter[];
+  parameters?: Array<Referenceable<Parameter>>;
   schemes?: string[];
   deprecated?: boolean;
   security?: Security[];
   tags?: string[];
 }
 
+// ----------------------------- Reference -----------------------------------
+export type Referenceable<T> = { $ref: string; } | T;
+
 // ----------------------------- Response ------------------------------------
 export interface Response {
   description: string;
-  schema?: Schema;
+  schema?: Referenceable<Schema>;
   headers?: { [headerName: string]: Header };
   examples?: { [exampleName: string]: {} };
 }
@@ -135,14 +138,14 @@ export interface BaseSchema {
   minProperties?: number;
   enum?: Array<string | boolean | number | {}>;
   type?: string;
-  items?: Schema|Schema[];
+  items?: Referenceable<Schema>|Array<Referenceable<Schema>>;
 }
 
 export interface Schema extends BaseSchema {
   $ref?: string;
-  allOf?: Schema[];
-  additionalProperties?: Schema;
-  properties?: {[propertyName: string]: Schema};
+  allOf?: Array<Referenceable<Schema>>;
+  additionalProperties?: Referenceable<Schema>;
+  properties?: {[propertyName: string]: Referenceable<Schema>};
   discriminator?: string;
   readOnly?: boolean;
   xml?: XML;
@@ -221,8 +224,8 @@ export interface Spec {
   schemes?: string[];
   consumes?: string[];
   produces?: string[];
-  paths: {[pathName: string]: Path};
-  definitions?: {[definitionsName: string]: Schema };
+  paths: {[pathName: string]: Referenceable<Path>};
+  definitions?: {[definitionsName: string]: Referenceable<Schema> };
   parameters?: {[parameterName: string]: BodyParameter|QueryParameter};
   responses?: {[responseName: string]: Response };
   security?: Array<{[securityDefinitionName: string]: string[]}>;

types/swagger-schema-official/swagger-schema-official-tests.ts

@@ -1335,3 +1335,61 @@ const basic_auth: swagger.Spec = {
   },
   "security": [{basicAuth: []}]
 };
+
+const reference_support: swagger.Spec = {
+    "swagger": "2.0",
+    "info": {
+        "version": "1.0.0",
+        "title": "Swagger Petstore"
+    },
+    "definitions": {
+        "stringSchema": {
+            "type": "string"
+        }
+    },
+    "parameters": {
+        "operationParameter": {
+            "in": "query",
+            "name": "operationParameter",
+            "type": "integer",
+            "description": "A sample operation parameter"
+        },
+        "pathParameter": {
+            "in": "query",
+            "name": "pathParameter",
+            "type": "string",
+            "description": "A sample path parameter"
+        }
+    },
+    "paths": {
+        "/path": {
+            "get": {
+                "parameters": [
+                    {"$ref": "#/parameters/operationParameter"}
+                ],
+                "responses": {
+                    "200": {
+                        "$ref": "#/responses/sampleResponse"
+                    },
+                    "404": {
+                      "description": "A sample response with a Schema reference.",
+                      "schema": {
+                          "$ref": "stringSchema"
+                      }
+                    }
+                }
+            },
+            "parameters": [
+                {"$ref": "#/parameters/pathParameter"}
+            ]
+        }
+    },
+    "responses": {
+        "sampleResponse" : {
+            "description": "A sample response.",
+            "schema": {
+                "type": "string"
+            }
+        }
+    }
+};