Merge pull request #3424 from daniseijo/extensions-info-section

feat(document-builder): add support for setting extensions inside the info object

Author: kamilmysliwiec

e2e/api-spec.json

@@ -1684,7 +1684,10 @@
     "title": "Cats example",
     "description": "The cats API description",
     "version": "1.0",
-    "contact": {}
+    "contact": {},
+    "x-logo": {
+      "url": "https://example.com/logo.png"
+    }
   },
   "tags": [
     {
@@ -2114,5 +2117,8 @@
       "basic": [],
       "cookie": []
     }
-  ]
+  ],
+  "x-test": {
+    "test": "test"
+  }
 }

e2e/validate-schema.e2e-spec.ts

@@ -64,6 +64,8 @@ describe('Validate OpenAPI schema', () => {
         in: 'header',
         schema: { type: 'string' }
       })
+      .addExtension('x-test', { test: 'test' })
+      .addExtension('x-logo', { url: 'https://example.com/logo.png' }, 'info')
       .build();
   });
 
@@ -219,7 +221,7 @@ describe('Validate OpenAPI schema', () => {
     expect(api.components.schemas).toHaveProperty('Cat');
   });
 
-  it('should consider explicit config over auto-detected schema', async () => {
+  it('should consider explicit config over auto-detected schema', () => {
     const document = SwaggerModule.createDocument(app, options);
     expect(document.paths['/api/cats/download'].get.responses).toEqual({
       '200': {
@@ -234,10 +236,30 @@ describe('Validate OpenAPI schema', () => {
     });
   });
 
-  it('should not add optional properties to required list', async () => {
+  it('should not add optional properties to required list', () => {
     const document = SwaggerModule.createDocument(app, options);
     const required = (document.components?.schemas?.Cat as SchemaObject)
       ?.required;
     expect(required).not.toContain('optionalRawDefinition');
   });
+
+  it('should fail if extension is not prefixed with x-', () => {
+    expect(() =>
+      new DocumentBuilder().addExtension('test', { test: 'test' }).build()
+    ).toThrow(
+      'Extension key is not prefixed. Please ensure you prefix it with `x-`.'
+    );
+  });
+
+  it('should add extension to root', () => {
+    const document = SwaggerModule.createDocument(app, options);
+    expect(document['x-test']).toEqual({ test: 'test' });
+  });
+
+  it('should add extension to info', () => {
+    const document = SwaggerModule.createDocument(app, options);
+    expect(document.info['x-logo']).toEqual({
+      url: 'https://example.com/logo.png'
+    });
+  });
 });

lib/document-builder.ts

@@ -4,6 +4,7 @@ import { ApiResponseOptions } from './decorators/api-response.decorator';
 import { buildDocumentBase } from './fixtures/document.base';
 import { OpenAPIObject } from './interfaces';
 import {
+  ExtensionLocation,
   ExternalDocumentationObject,
   ParameterObject,
   SecurityRequirementObject,
@@ -76,6 +77,9 @@ export class DocumentBuilder {
     return this;
   }
 
+  /**
+   * @deprecated Use `addServer` method to set up multiple different paths. The `setBasePath` method has been deprecated. Now, a global prefix is populated automatically. If you want to ignore it, take a look here: https://docs.nestjs.com/recipes/swagger#global-prefix.
+   */
   public setBasePath(path: string) {
     this.logger.warn(
       'The "setBasePath" method has been deprecated. Now, a global prefix is populated automatically. If you want to ignore it, take a look here: https://docs.nestjs.com/recipes/swagger#global-prefix. Alternatively, you can use "addServer" method to set up multiple different paths.'
@@ -101,14 +105,22 @@ export class DocumentBuilder {
     return this;
   }
 
-  public addExtension(extensionKey: string, extensionProperties: any): this {
+  public addExtension(
+    extensionKey: string,
+    extensionProperties: any,
+    location: ExtensionLocation = 'root'
+  ): this {
     if (!extensionKey.startsWith('x-')) {
       throw new Error(
         'Extension key is not prefixed. Please ensure you prefix it with `x-`.'
       );
     }
 
-    this.document[extensionKey] = clone(extensionProperties);
+    if (location === 'root') {
+      this.document[extensionKey] = clone(extensionProperties);
+    } else {
+      this.document[location][extensionKey] = clone(extensionProperties);
+    }
 
     return this;
   }

lib/interfaces/open-api-spec.interface.ts

@@ -287,3 +287,5 @@ export interface OAuthFlowObject {
 
 export type ScopesObject = Record<string, any>;
 export type SecurityRequirementObject = Record<string, string[]>;
+
+export type ExtensionLocation = 'root' | 'info';