chore: add OpenAPI 3.0.x interface

Author: mrlubos

Diff for: .nvmrc

@@ -1 +1 @@
-20.10.0
+22.11.0

Diff for: packages/openapi-ts/src/index.ts

@@ -439,6 +439,6 @@ export default {
   defineConfig,
 };
 
-export type { OpenApiV3_0_0 } from './openApi/3.0.x';
-export type { OpenApiV3_1_0 } from './openApi/3.1.x';
+export type { OpenApiV3_0_X } from './openApi/3.0.x';
+export type { OpenApiV3_1_X } from './openApi/3.1.x';
 export type { UserConfig } from './types/config';

Diff for: packages/openapi-ts/src/openApi/3.0.x/index.ts

@@ -1,2 +1,2 @@
-export { parseV3_0_0 } from './parser';
-export type { OpenApiV3_0_0 } from './types/spec';
+export { parseV3_0_X } from './parser';
+export type { OpenApiV3_0_X } from './types/spec';

Diff for: packages/openapi-ts/src/openApi/3.0.x/parser/index.ts

@@ -1,7 +1,7 @@
 import type { IRContext } from '../../../ir/context';
-import type { OpenApiV3_0_0 } from '../types/spec';
+import type { OpenApiV3_0_X } from '../types/spec';
 
-export const parseV3_0_0 = (context: IRContext<OpenApiV3_0_0>) => {
+export const parseV3_0_X = (context: IRContext<OpenApiV3_0_X>) => {
   // TODO
   console.log(context.spec);
 };

Diff for: packages/openapi-ts/src/openApi/3.0.x/types/spec.d.ts

@@ -1,2 +1,2 @@
-export { parseV3_1_0 } from './parser';
-export type { OpenApiV3_1_0 } from './types/spec';
+export { parseV3_1_X } from './parser';
+export type { OpenApiV3_1_X } from './types/spec';

Diff for: packages/openapi-ts/src/openApi/3.1.x/index.ts

@@ -1,6 +1,6 @@
 import type { IRContext } from '../../../ir/context';
 import type {
-  OpenApiV3_1_0,
+  OpenApiV3_1_X,
   ParameterObject,
   PathItemObject,
   PathsObject,
@@ -13,7 +13,7 @@ import {
 } from './parameter';
 import { parseSchema } from './schema';
 
-export const parseV3_1_0 = (context: IRContext<OpenApiV3_1_0>) => {
+export const parseV3_1_X = (context: IRContext<OpenApiV3_1_X>) => {
   const operationIds = new Map<string, string>();
 
   for (const path in context.spec.paths) {

Diff for: packages/openapi-ts/src/openApi/3.1.x/parser/index.ts

@@ -1,7 +1,5 @@
-import type {
-  EnumExtensions,
-  OpenApiSchemaExtensions,
-} from './spec-extensions';
+import type { EnumExtensions } from '../../common/types/openapi-spec-extensions';
+import type { OpenApiSchemaExtensions } from './spec-extensions';
 
 // TODO: left out some keywords related to structuring a complex schema and declaring a dialect
 export interface JsonSchemaDraft2020_12

Diff for: packages/openapi-ts/src/openApi/3.1.x/types/json-schema-draft-2020-12.d.ts

@@ -4,21 +4,6 @@ import type {
   XMLObject,
 } from './spec';
 
-export interface EnumExtensions {
-  /**
-   * `x-enum-descriptions` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator.
-   */
-  'x-enum-descriptions'?: ReadonlyArray<string>;
-  /**
-   * `x-enum-varnames` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator.
-   */
-  'x-enum-varnames'?: ReadonlyArray<string>;
-  /**
-   * {@link https://github.com/RicoSuter/NSwag NSwag} generates `x-enumNames` field containing custom enum names.
-   */
-  'x-enumNames'?: ReadonlyArray<string>;
-}
-
 export interface OpenApiSchemaExtensions {
   /**
    * Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#composition-and-inheritance-polymorphism Composition and Inheritance} for more details.

Diff for: packages/openapi-ts/src/openApi/3.1.x/types/spec-extensions.d.ts

@@ -5,7 +5,7 @@ import type { JsonSchemaDraft2020_12 } from './json-schema-draft-2020-12';
  *
  * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}.
  */
-export interface OpenApiV3_1_0 {
+export interface OpenApiV3_1_X {
   /**
    * An element to hold various schemas for the document.
    */
@@ -493,7 +493,14 @@ export interface EncodingObject {
   /**
    * Describes how a specific property value will be serialized depending on its type. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object Parameter Object} for details on the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle `style`} property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#encodingContentType `contentType`} (implicit or explicit) SHALL be ignored.
    */
-  style?: string;
+  style?:
+    | 'deepObject'
+    | 'form'
+    | 'label'
+    | 'matrix'
+    | 'pipeDelimited'
+    | 'simple'
+    | 'spaceDelimited';
 }
 
 /**
@@ -1622,7 +1629,7 @@ export interface ResponsesObject {
   /**
    * Any {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#http-status-codes HTTP status code} can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
    */
-  [statusCode: string]: ResponseObject | ReferenceObject | undefined;
+  [httpStatusCode: string]: ResponseObject | ReferenceObject | undefined;
   /**
    * The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses.
    */

Diff for: packages/openapi-ts/src/openApi/3.1.x/types/spec.d.ts

@@ -1,19 +1,19 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { type OpenApi, parseExperimental, parseLegacy } from '..';
-import type { OpenApiV3_0_0 } from '../3.0.x';
-import { parseV3_0_0 } from '../3.0.x';
-import type { OpenApiV3_1_0 } from '../3.1.x';
-import { parseV3_1_0 } from '../3.1.x';
+import type { OpenApiV3_0_X } from '../3.0.x';
+import { parseV3_0_X } from '../3.0.x';
+import type { OpenApiV3_1_X } from '../3.1.x';
+import { parseV3_1_X } from '../3.1.x';
 import type { ParserConfig } from '../config';
 import * as parseV2 from '../v2';
 import * as parseV3 from '../v3';
 
 vi.mock('../3.0.x', () => ({
-  parseV3_0_0: vi.fn(),
+  parseV3_0_X: vi.fn(),
 }));
 vi.mock('../3.1.x', () => ({
-  parseV3_1_0: vi.fn(),
+  parseV3_1_X: vi.fn(),
 }));
 
 const parserConfig: ParserConfig = {
@@ -111,92 +111,97 @@ describe('experimentalParser', () => {
   });
 
   it('handles OpenAPI 3.0.0', () => {
-    const spec: OpenApiV3_0_0 = {
-      // info: {
-      //   title: '',
-      //   version: '1',
-      // },
+    const spec: OpenApiV3_0_X = {
+      info: {
+        title: '',
+        version: '1',
+      },
       openapi: '3.0.0',
+      paths: {},
     };
     parseExperimental({
       // @ts-ignore
       config: {},
       parserConfig,
       spec,
     });
-    expect(parseV3_0_0).toHaveBeenCalled();
+    expect(parseV3_0_X).toHaveBeenCalled();
   });
 
   it('handles OpenAPI 3.0.1', () => {
-    const spec: OpenApiV3_0_0 = {
-      // info: {
-      //   title: '',
-      //   version: '1',
-      // },
+    const spec: OpenApiV3_0_X = {
+      info: {
+        title: '',
+        version: '1',
+      },
       openapi: '3.0.1',
+      paths: {},
     };
     parseExperimental({
       // @ts-ignore
       config: {},
       parserConfig,
       spec,
     });
-    expect(parseV3_0_0).toHaveBeenCalled();
+    expect(parseV3_0_X).toHaveBeenCalled();
   });
 
   it('handles OpenAPI 3.0.2', () => {
-    const spec: OpenApiV3_0_0 = {
-      // info: {
-      //   title: '',
-      //   version: '1',
-      // },
+    const spec: OpenApiV3_0_X = {
+      info: {
+        title: '',
+        version: '1',
+      },
       openapi: '3.0.2',
+      paths: {},
     };
     parseExperimental({
       // @ts-ignore
       config: {},
       parserConfig,
       spec,
     });
-    expect(parseV3_0_0).toHaveBeenCalled();
+    expect(parseV3_0_X).toHaveBeenCalled();
   });
 
   it('handles OpenAPI 3.0.3', () => {
-    const spec: OpenApiV3_0_0 = {
-      // info: {
-      //   title: '',
-      //   version: '1',
-      // },
+    const spec: OpenApiV3_0_X = {
+      info: {
+        title: '',
+        version: '1',
+      },
       openapi: '3.0.3',
+      paths: {},
     };
     parseExperimental({
       // @ts-ignore
       config: {},
       parserConfig,
       spec,
     });
-    expect(parseV3_0_0).toHaveBeenCalled();
+    expect(parseV3_0_X).toHaveBeenCalled();
   });
 
   it('handles OpenAPI 3.0.4', () => {
-    const spec: OpenApiV3_0_0 = {
-      // info: {
-      //   title: '',
-      //   version: '1',
-      // },
+    const spec: OpenApiV3_0_X = {
+      info: {
+        title: '',
+        version: '1',
+      },
       openapi: '3.0.4',
+      paths: {},
     };
     parseExperimental({
       // @ts-ignore
       config: {},
       parserConfig,
       spec,
     });
-    expect(parseV3_0_0).toHaveBeenCalled();
+    expect(parseV3_0_X).toHaveBeenCalled();
   });
 
   it('handles OpenAPI 3.1.0', () => {
-    const spec: OpenApiV3_1_0 = {
+    const spec: OpenApiV3_1_X = {
       info: {
         title: '',
         version: '1',
@@ -209,11 +214,11 @@ describe('experimentalParser', () => {
       parserConfig,
       spec,
     });
-    expect(parseV3_1_0).toHaveBeenCalled();
+    expect(parseV3_1_X).toHaveBeenCalled();
   });
 
   it('handles OpenAPI 3.1.1', () => {
-    const spec: OpenApiV3_1_0 = {
+    const spec: OpenApiV3_1_X = {
       info: {
         title: '',
         version: '1',
@@ -226,6 +231,6 @@ describe('experimentalParser', () => {
       parserConfig,
       spec,
     });
-    expect(parseV3_1_0).toHaveBeenCalled();
+    expect(parseV3_1_X).toHaveBeenCalled();
   });
 });

Diff for: packages/openapi-ts/src/openApi/__tests__/index.spec.ts

@@ -0,0 +1,14 @@
+export interface EnumExtensions {
+  /**
+   * `x-enum-descriptions` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator.
+   */
+  'x-enum-descriptions'?: ReadonlyArray<string>;
+  /**
+   * `x-enum-varnames` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator.
+   */
+  'x-enum-varnames'?: ReadonlyArray<string>;
+  /**
+   * {@link https://github.com/RicoSuter/NSwag NSwag} generates `x-enumNames` field containing custom enum names.
+   */
+  'x-enumNames'?: ReadonlyArray<string>;
+}

Diff for: packages/openapi-ts/src/openApi/common/types/openapi-spec-extensions.d.ts

@@ -1,7 +1,7 @@
 import { IRContext } from '../ir/context';
 import type { Config } from '../types/config';
-import { type OpenApiV3_0_0, parseV3_0_0 } from './3.0.x';
-import { type OpenApiV3_1_0, parseV3_1_0 } from './3.1.x';
+import { type OpenApiV3_0_X, parseV3_0_X } from './3.0.x';
+import { type OpenApiV3_1_X, parseV3_1_X } from './3.1.x';
 import type { Client } from './common/interfaces/client';
 import type { OpenApi } from './common/interfaces/OpenApi';
 import type { ParserConfig } from './config';
@@ -73,19 +73,19 @@ export const parseExperimental = ({
     spec: spec as Record<string, any>,
   });
 
-  const ctx = context as IRContext<OpenApiV3_0_0 | OpenApiV3_1_0>;
+  const ctx = context as IRContext<OpenApiV3_0_X | OpenApiV3_1_X>;
   switch (ctx.spec.openapi) {
     // TODO: parser - handle Swagger 2.0
     case '3.0.0':
     case '3.0.1':
     case '3.0.2':
     case '3.0.3':
     case '3.0.4':
-      parseV3_0_0(context as IRContext<OpenApiV3_0_0>);
+      parseV3_0_X(context as IRContext<OpenApiV3_0_X>);
       break;
     case '3.1.0':
     case '3.1.1':
-      parseV3_1_0(context as IRContext<OpenApiV3_1_0>);
+      parseV3_1_X(context as IRContext<OpenApiV3_1_X>);
       break;
     default:
       // TODO: parser - uncomment after removing legacy parser.