openapi-types: support x- specification extensions everywhere without a pre-existing index signature (fixes #768)

Author: mitchell-merry

package-lock.json

@@ -43,7 +43,7 @@
     "lerna": "^3.22.1",
     "mocha": "10.2.0",
     "nyc": "15.1.0",
-    "prettier": "^2.0.0",
+    "prettier": "^2.2.0",
     "source-map-support": "0.5.17",
     "supertest": "4.0.1",
     "ts-node": "8.8.2",

package.json

@@ -1,5 +1,10 @@
 /* tslint:disable:no-namespace no-empty-interface */
 export namespace OpenAPI {
+  export type SpecificationExtensionKey = `x-${string}`;
+  export interface Extensible {
+    [key: SpecificationExtensionKey]: unknown;
+  }
+
   // OpenAPI extensions can be declared using generics
   // e.g.:
   // OpenAPI.Document<{
@@ -268,7 +273,7 @@ export namespace OpenAPIV3_1 {
 }
 
 export namespace OpenAPIV3 {
-  export interface Document<T extends {} = {}> {
+  export interface Document<T extends {} = {}> extends OpenAPI.Extensible {
     openapi: string;
     info: InfoObject;
     servers?: ServerObject[];
@@ -284,7 +289,7 @@ export namespace OpenAPIV3 {
     'x-express-openapi-validation-strict'?: boolean;
   }
 
-  export interface InfoObject {
+  export interface InfoObject extends OpenAPI.Extensible {
     title: string;
     description?: string;
     termsOfService?: string;
@@ -293,24 +298,24 @@ export namespace OpenAPIV3 {
     version: string;
   }
 
-  export interface ContactObject {
+  export interface ContactObject extends OpenAPI.Extensible {
     name?: string;
     url?: string;
     email?: string;
   }
 
-  export interface LicenseObject {
+  export interface LicenseObject extends OpenAPI.Extensible {
     name: string;
     url?: string;
   }
 
-  export interface ServerObject {
+  export interface ServerObject extends OpenAPI.Extensible {
     url: string;
     description?: string;
     variables?: { [variable: string]: ServerVariableObject };
   }
 
-  export interface ServerVariableObject {
+  export interface ServerVariableObject extends OpenAPI.Extensible {
     enum?: string[];
     default: string;
     description?: string;
@@ -343,7 +348,8 @@ export namespace OpenAPIV3 {
     parameters?: (ReferenceObject | ParameterObject)[];
   } & {
     [method in HttpMethods]?: OperationObject<T>;
-  };
+  } &
+    OpenAPI.Extensible;
 
   export type OperationObject<T extends {} = {}> = {
     tags?: string[];
@@ -358,9 +364,10 @@ export namespace OpenAPIV3 {
     deprecated?: boolean;
     security?: SecurityRequirementObject[];
     servers?: ServerObject[];
-  } & T;
+  } & T &
+    OpenAPI.Extensible;
 
-  export interface ExternalDocumentationObject {
+  export interface ExternalDocumentationObject extends OpenAPI.Extensible {
     description?: string;
     url: string;
   }
@@ -372,7 +379,7 @@ export namespace OpenAPIV3 {
 
   export interface HeaderObject extends ParameterBaseObject {}
 
-  export interface ParameterBaseObject {
+  export interface ParameterBaseObject extends OpenAPI.Extensible {
     description?: string;
     required?: boolean;
     deprecated?: boolean;
@@ -403,7 +410,7 @@ export namespace OpenAPIV3 {
     type?: NonArraySchemaObjectType;
   }
 
-  export interface BaseSchemaObject {
+  export interface BaseSchemaObject extends OpenAPI.Extensible {
     // JSON schema allowed properties, adjusted for OpenAPI
     title?: string;
     description?: string;
@@ -444,46 +451,46 @@ export namespace OpenAPIV3 {
     deprecated?: boolean;
   }
 
-  export interface DiscriminatorObject {
+  export interface DiscriminatorObject extends OpenAPI.Extensible {
     propertyName: string;
     mapping?: { [value: string]: string };
   }
 
-  export interface XMLObject {
+  export interface XMLObject extends OpenAPI.Extensible {
     name?: string;
     namespace?: string;
     prefix?: string;
     attribute?: boolean;
     wrapped?: boolean;
   }
 
-  export interface ReferenceObject {
+  export interface ReferenceObject extends OpenAPI.Extensible {
     $ref: string;
   }
 
-  export interface ExampleObject {
+  export interface ExampleObject extends OpenAPI.Extensible {
     summary?: string;
     description?: string;
     value?: any;
     externalValue?: string;
   }
 
-  export interface MediaTypeObject {
+  export interface MediaTypeObject extends OpenAPI.Extensible {
     schema?: ReferenceObject | SchemaObject;
     example?: any;
     examples?: { [media: string]: ReferenceObject | ExampleObject };
     encoding?: { [media: string]: EncodingObject };
   }
 
-  export interface EncodingObject {
+  export interface EncodingObject extends OpenAPI.Extensible {
     contentType?: string;
     headers?: { [header: string]: ReferenceObject | HeaderObject };
     style?: string;
     explode?: boolean;
     allowReserved?: boolean;
   }
 
-  export interface RequestBodyObject {
+  export interface RequestBodyObject extends OpenAPI.Extensible {
     description?: string;
     content: { [media: string]: MediaTypeObject };
     required?: boolean;
@@ -493,14 +500,14 @@ export namespace OpenAPIV3 {
     [code: string]: ReferenceObject | ResponseObject;
   }
 
-  export interface ResponseObject {
+  export interface ResponseObject extends OpenAPI.Extensible {
     description: string;
     headers?: { [header: string]: ReferenceObject | HeaderObject };
     content?: { [media: string]: MediaTypeObject };
     links?: { [link: string]: ReferenceObject | LinkObject };
   }
 
-  export interface LinkObject {
+  export interface LinkObject extends OpenAPI.Extensible {
     operationRef?: string;
     operationId?: string;
     parameters?: { [parameter: string]: any };
@@ -517,7 +524,7 @@ export namespace OpenAPIV3 {
     [name: string]: string[];
   }
 
-  export interface ComponentsObject {
+  export interface ComponentsObject extends OpenAPI.Extensible {
     schemas?: { [key: string]: ReferenceObject | SchemaObject };
     responses?: { [key: string]: ReferenceObject | ResponseObject };
     parameters?: { [key: string]: ReferenceObject | ParameterObject };
@@ -535,21 +542,21 @@ export namespace OpenAPIV3 {
     | OAuth2SecurityScheme
     | OpenIdSecurityScheme;
 
-  export interface HttpSecurityScheme {
+  export interface HttpSecurityScheme extends OpenAPI.Extensible {
     type: 'http';
     description?: string;
     scheme: string;
     bearerFormat?: string;
   }
 
-  export interface ApiKeySecurityScheme {
+  export interface ApiKeySecurityScheme extends OpenAPI.Extensible {
     type: 'apiKey';
     description?: string;
     name: string;
     in: string;
   }
 
-  export interface OAuth2SecurityScheme {
+  export interface OAuth2SecurityScheme extends OpenAPI.Extensible {
     type: 'oauth2';
     description?: string;
     flows: {
@@ -577,21 +584,21 @@ export namespace OpenAPIV3 {
     };
   }
 
-  export interface OpenIdSecurityScheme {
+  export interface OpenIdSecurityScheme extends OpenAPI.Extensible {
     type: 'openIdConnect';
     description?: string;
     openIdConnectUrl: string;
   }
 
-  export interface TagObject {
+  export interface TagObject extends OpenAPI.Extensible {
     name: string;
     description?: string;
     externalDocs?: ExternalDocumentationObject;
   }
 }
 
 export namespace OpenAPIV2 {
-  export interface Document<T extends {} = {}> {
+  export interface Document<T extends {} = {}> extends OpenAPI.Extensible {
     basePath?: string;
     consumes?: MimeTypes;
     definitions?: DefinitionsObject;
@@ -614,13 +621,13 @@ export namespace OpenAPIV2 {
     'x-express-openapi-validation-strict'?: boolean;
   }
 
-  export interface TagObject {
+  export interface TagObject extends OpenAPI.Extensible {
     name: string;
     description?: string;
     externalDocs?: ExternalDocumentationObject;
   }
 
-  export interface SecuritySchemeObjectBase {
+  export interface SecuritySchemeObjectBase extends OpenAPI.Extensible {
     type: 'basic' | 'apiKey' | 'oauth2';
     description?: string;
   }
@@ -689,7 +696,7 @@ export namespace OpenAPIV2 {
     [index: string]: string[];
   }
 
-  export interface ReferenceObject {
+  export interface ReferenceObject extends OpenAPI.Extensible {
     $ref: string;
   }
 
@@ -701,7 +708,7 @@ export namespace OpenAPIV2 {
 
   export type Schema = SchemaObject | ReferenceObject;
 
-  export interface ResponseObject {
+  export interface ResponseObject extends OpenAPI.Extensible {
     description: string;
     schema?: Schema;
     headers?: HeadersObject;
@@ -720,13 +727,6 @@ export namespace OpenAPIV2 {
     [index: string]: any;
   }
 
-  export interface ResponseObject {
-    description: string;
-    schema?: Schema;
-    headers?: HeadersObject;
-    examples?: ExampleObject;
-  }
-
   export type OperationObject<T extends {} = {}> = {
     tags?: string[];
     summary?: string;
@@ -740,7 +740,8 @@ export namespace OpenAPIV2 {
     schemes?: string[];
     deprecated?: boolean;
     security?: SecurityRequirementObject[];
-  } & T;
+  } & T &
+    OpenAPI.Extensible;
 
   export interface ResponsesObject {
     [index: string]: Response | undefined;
@@ -802,7 +803,7 @@ export namespace OpenAPIV2 {
     [index: string]: SchemaObject;
   }
 
-  export interface SchemaObject extends IJsonSchema {
+  export interface SchemaObject extends IJsonSchema, OpenAPI.Extensible {
     [index: string]: any;
     discriminator?: string;
     readOnly?: boolean;
@@ -822,7 +823,7 @@ export namespace OpenAPIV2 {
     url: string;
   }
 
-  export interface ItemsObject {
+  export interface ItemsObject extends OpenAPI.Extensible {
     type: string;
     format?: string;
     items?: ItemsObject | ReferenceObject;
@@ -852,7 +853,7 @@ export namespace OpenAPIV2 {
     wrapped?: boolean;
   }
 
-  export interface InfoObject {
+  export interface InfoObject extends OpenAPI.Extensible {
     title: string;
     description?: string;
     termsOfService?: string;
@@ -861,13 +862,13 @@ export namespace OpenAPIV2 {
     version: string;
   }
 
-  export interface ContactObject {
+  export interface ContactObject extends OpenAPI.Extensible {
     name?: string;
     url?: string;
     email?: string;
   }
 
-  export interface LicenseObject {
+  export interface LicenseObject extends OpenAPI.Extensible {
     name: string;
     url?: string;
   }