feat(OpenAPI 3.1.0): add new schema for 3.1.0

This involved breaking 2 and 3 out a little to better mirror the
differences in the specs

Author: jefflembeck

packages/cli/src/swagger/specGenerator.ts

@@ -3,7 +3,10 @@ import { Tsoa, assertNever, Swagger } from '@tsoa/runtime';
 import * as handlebars from 'handlebars';
 
 export abstract class SpecGenerator {
-  constructor(protected readonly metadata: Tsoa.Metadata, protected readonly config: ExtendedSpecConfig) {}
+  constructor(
+    protected readonly metadata: Tsoa.Metadata,
+    protected readonly config: ExtendedSpecConfig,
+  ) {}
 
   protected buildAdditionalProperties(type: Tsoa.Type) {
     return this.getSwaggerType(type);
@@ -59,7 +62,7 @@ export abstract class SpecGenerator {
     }
   }
 
-  protected getSwaggerType(type: Tsoa.Type, title?: string): Swagger.Schema | Swagger.BaseSchema {
+  protected getSwaggerType(type: Tsoa.Type, title?: string): Swagger.BaseSchema {
     if (type.dataType === 'void' || type.dataType === 'undefined') {
       return this.getSwaggerTypeForVoid(type.dataType);
     } else if (type.dataType === 'refEnum' || type.dataType === 'refObject' || type.dataType === 'refAlias') {
@@ -96,13 +99,13 @@ export abstract class SpecGenerator {
     }
   }
 
-  protected abstract getSwaggerTypeForUnionType(type: Tsoa.UnionType, title?: string): Swagger.Schema | Swagger.BaseSchema;
+  protected abstract getSwaggerTypeForUnionType(type: Tsoa.UnionType, title?: string): Swagger.BaseSchema;
 
-  protected abstract getSwaggerTypeForIntersectionType(type: Tsoa.IntersectionType, title?: string): Swagger.Schema | Swagger.BaseSchema;
+  protected abstract getSwaggerTypeForIntersectionType(type: Tsoa.IntersectionType, title?: string): Swagger.BaseSchema;
 
-  protected abstract buildProperties(properties: Tsoa.Property[]): { [propertyName: string]: Swagger.Schema | Swagger.Schema3 };
+  protected abstract buildProperties(properties: Tsoa.Property[]): { [propertyName: string]: Swagger.Schema2 } | { [propertyName: string]: Swagger.Schema3 };
 
-  public getSwaggerTypeForObjectLiteral(objectLiteral: Tsoa.NestedObjectLiteralType, title?: string): Swagger.Schema {
+  public getSwaggerTypeForObjectLiteral(objectLiteral: Tsoa.NestedObjectLiteralType, title?: string): Swagger.BaseSchema {
     const properties = this.buildProperties(objectLiteral.properties);
 
     const additionalProperties = objectLiteral.additionalProperties && this.getSwaggerType(objectLiteral.additionalProperties);
@@ -146,7 +149,7 @@ export abstract class SpecGenerator {
     }
   };
 
-  protected getSwaggerTypeForPrimitiveType(dataType: Tsoa.PrimitiveTypeLiteral): Swagger.Schema {
+  protected getSwaggerTypeForPrimitiveType(dataType: Tsoa.PrimitiveTypeLiteral): Swagger.BaseSchema {
     if (dataType === 'object') {
       if (process.env.NODE_ENV !== 'tsoa_test') {
         // eslint-disable-next-line no-console
@@ -162,7 +165,7 @@ export abstract class SpecGenerator {
       }
     }
 
-    const map: Record<Tsoa.PrimitiveTypeLiteral, Swagger.Schema> = {
+    const map: Record<Tsoa.PrimitiveTypeLiteral, Swagger.BaseSchema> = {
       any: {
         // While the any type is discouraged, it does explicitly allows anything, so it should always allow additionalProperties
         additionalProperties: true,
@@ -188,7 +191,7 @@ export abstract class SpecGenerator {
     return map[dataType];
   }
 
-  protected getSwaggerTypeForArrayType(arrayType: Tsoa.ArrayType, title?: string): Swagger.Schema {
+  protected getSwaggerTypeForArrayType(arrayType: Tsoa.ArrayType, title?: string): Swagger.BaseSchema {
     return {
       items: this.getSwaggerType(arrayType.elementType, title),
       type: 'array',

packages/cli/src/swagger/specGenerator2.ts

@@ -227,7 +227,7 @@ export class SpecGenerator2 extends SpecGenerator {
         if (res.produces) {
           produces.push(...res.produces);
         }
-        swaggerResponses[res.name].schema = this.getSwaggerType(res.schema) as Swagger.Schema;
+        swaggerResponses[res.name].schema = this.getSwaggerType(res.schema) as Swagger.Schema2;
       }
       if (res.examples && res.examples[0]) {
         if ((res.exampleLabels?.filter(e => e).length || 0) > 0) {
@@ -307,7 +307,7 @@ export class SpecGenerator2 extends SpecGenerator {
         title: `${this.getOperationId(controllerName, method)}Body`,
         type: 'object',
       },
-    } as Swagger.Parameter;
+    } as Swagger.Parameter2;
     if (required.length) {
       parameter.schema.required = required;
     }
@@ -324,17 +324,6 @@ export class SpecGenerator2 extends SpecGenerator {
   }
 
   private buildParameter(source: Tsoa.Parameter): Swagger.Parameter2 {
-    let parameter = {
-      default: source.default,
-      description: source.description,
-      in: source.in,
-      name: source.name,
-      required: this.isRequiredWithoutDefault(source),
-    } as Swagger.Parameter2;
-    if (source.deprecated) {
-      parameter['x-deprecated'] = true;
-    }
-
     let type = source.type;
 
     if (source.in !== 'body' && source.type.dataType === 'refEnum') {
@@ -348,16 +337,23 @@ export class SpecGenerator2 extends SpecGenerator {
     }
 
     const parameterType = this.getSwaggerType(type);
-    if (parameterType.format) {
-      parameter.format = this.throwIfNotDataFormat(parameterType.format);
-    }
+
+    let parameter = {
+      default: source.default,
+      description: source.description,
+      in: source.in,
+      name: source.name,
+      required: this.isRequiredWithoutDefault(source),
+      ...(source.deprecated ? { 'x-deprecated': true } : {}),
+      ...(parameterType.$ref ? { schema: parameterType } : {}),
+      ...(parameterType.format ? { format: this.throwIfNotDataFormat(parameterType.format) } : {}),
+    } as Swagger.Parameter2;
 
     if (Swagger.isQueryParameter(parameter) && parameterType.type === 'array') {
       parameter.collectionFormat = 'multi';
     }
 
-    if (parameterType.$ref) {
-      parameter.schema = parameterType as Swagger.Schema2;
+    if (parameter.schema) {
       return parameter;
     }
 

packages/cli/src/swagger/specGenerator3.ts

@@ -503,7 +503,7 @@ export class SpecGenerator3 extends SpecGenerator {
     }
 
     if (parameterType.$ref) {
-      parameter.schema = parameterType as Swagger.Schema;
+      parameter.schema = parameterType as Swagger.Schema3;
       return parameter;
     }
 
@@ -581,7 +581,7 @@ export class SpecGenerator3 extends SpecGenerator {
     return { $ref: `#/components/schemas/${encodeURIComponent(referenceType.refName)}` };
   }
 
-  protected getSwaggerTypeForPrimitiveType(dataType: Tsoa.PrimitiveTypeLiteral): Swagger.Schema {
+  protected getSwaggerTypeForPrimitiveType(dataType: Tsoa.PrimitiveTypeLiteral): Swagger.BaseSchema {
     if (dataType === 'any') {
       // Setting additionalProperties causes issues with code generators for OpenAPI 3
       // Therefore, we avoid setting it explicitly (since it's the implicit default already)
@@ -602,8 +602,8 @@ export class SpecGenerator3 extends SpecGenerator {
   // grouping enums is helpful because it makes the spec more readable and it
   // bypasses a failure in openapi-generator caused by using anyOf with
   // duplicate types.
-  private groupEnums(types: Array<Swagger.Schema | Swagger.BaseSchema>) {
-    const returnTypes: Array<Swagger.Schema | Swagger.BaseSchema> = [];
+  private groupEnums(types: Swagger.BaseSchema[]) {
+    const returnTypes: Swagger.BaseSchema[] = [];
     const enumValuesByType: Record<string, Record<string, boolean | string | number | null>> = {};
     for (const type of types) {
       if (type.enum && type.type) {
@@ -630,7 +630,7 @@ export class SpecGenerator3 extends SpecGenerator {
     return returnTypes;
   }
 
-  protected removeDuplicateSwaggerTypes(types: Array<Swagger.Schema | Swagger.BaseSchema>): Array<Swagger.Schema | Swagger.BaseSchema> {
+  protected removeDuplicateSwaggerTypes(types: Swagger.BaseSchema[]): Swagger.BaseSchema[] {
     if (types.length === 1) {
       return types;
     } else {

packages/runtime/src/metadataGeneration/tsoa.ts

@@ -49,6 +49,7 @@ export namespace Tsoa {
     validators: Validators;
     deprecated: boolean;
     exampleLabels?: Array<string | undefined>;
+    $ref?: Swagger.BaseSchema;
   }
 
   export interface ResParameter extends Response, Parameter {