add openapi 3.1 support (#5372)

This PR adds support for Open API 3.1 in the `@typespec/openapi3`
package.

The changes in this PR includes:
#4946 - adds `output-spec-versions` emitter option
#5035 - adds initial open api 3.1 schema emitter
#5245 - add support for tuples
#5246 - add support for enums backed by multiple types
#5310 - playground support for array of constants emitter options 
#5407 - add support for json-schema decorators
#5549 - add support for binary types in Open API 3.1

---------

Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>

Author: chrisradek

.chronus/changes/openapi3-json-decorators-2024-11-18-14-22-8.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Adds support for @typespec/json-schema decorators with Open API 3.0 and 3.1 emitters.

.chronus/changes/openapi3-output-spec-versions-2024-10-1-11-53-51.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Adds support for emitting Open API 3.1 models using the `openapi-versions` emitter configuration option.
+Open API 3.0 is emitted by default.

.chronus/changes/openapi31-playground-2025-0-9-12-38-34.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/playground"
+---
+
+Add support for displaying array-based emitter options

packages/openapi3/README.md

@@ -74,6 +74,10 @@ Example Multiple service with versioning
 - `openapi.Org1.Service2.v1.0.yaml`
 - `openapi.Org1.Service2.v1.1.yaml`
 
+### `openapi-versions`
+
+**Type:** `array`
+
 ### `new-line`
 
 **Type:** `"crlf" | "lf"`

packages/openapi3/package.json

@@ -65,10 +65,14 @@
   "peerDependencies": {
     "@typespec/compiler": "workspace:~",
     "@typespec/http": "workspace:~",
+    "@typespec/json-schema": "workspace:~",
     "@typespec/openapi": "workspace:~",
     "@typespec/versioning": "workspace:~"
   },
   "peerDependenciesMeta": {
+    "@typespec/json-schema": {
+      "optional": true
+    },
     "@typespec/xml": {
       "optional": true
     }
@@ -78,6 +82,7 @@
     "@types/yargs": "~17.0.33",
     "@typespec/compiler": "workspace:~",
     "@typespec/http": "workspace:~",
+    "@typespec/json-schema": "workspace:~",
     "@typespec/library-linter": "workspace:~",
     "@typespec/openapi": "workspace:~",
     "@typespec/rest": "workspace:~",

packages/openapi3/src/attach-extensions.ts

@@ -0,0 +1,12 @@
+import { Program, Type } from "@typespec/compiler";
+import { getExtensions } from "@typespec/openapi";
+
+export function attachExtensions(program: Program, type: Type, emitObject: any) {
+  // Attach any OpenAPI extensions
+  const extensions = getExtensions(program, type);
+  if (extensions) {
+    for (const key of extensions.keys()) {
+      emitObject[key] = extensions.get(key);
+    }
+  }
+}

packages/openapi3/src/encoding.ts

@@ -2,22 +2,24 @@ import { type ModelProperty, Program, type Scalar, getEncode } from "@typespec/c
 import { ObjectBuilder } from "@typespec/compiler/emitter-framework";
 import type { ResolvedOpenAPI3EmitterOptions } from "./openapi.js";
 import { getSchemaForStdScalars } from "./std-scalar-schemas.js";
-import type { OpenAPI3Schema } from "./types.js";
+import type { OpenAPI3Schema, OpenAPISchema3_1 } from "./types.js";
 
 export function applyEncoding(
   program: Program,
   typespecType: Scalar | ModelProperty,
-  target: OpenAPI3Schema,
+  target: OpenAPI3Schema | OpenAPISchema3_1,
+  getEncodedFieldName: (typespecType: Scalar | ModelProperty) => string,
   options: ResolvedOpenAPI3EmitterOptions,
-): OpenAPI3Schema {
+): OpenAPI3Schema & OpenAPISchema3_1 {
   const encodeData = getEncode(program, typespecType);
   if (encodeData) {
     const newTarget = new ObjectBuilder(target);
     const newType = getSchemaForStdScalars(encodeData.type as any, options);
     newTarget.type = newType.type;
     // If the target already has a format it takes priority. (e.g. int32)
-    newTarget.format = mergeFormatAndEncoding(
-      newTarget.format,
+    const encodedFieldName = getEncodedFieldName(typespecType);
+    newTarget[encodedFieldName] = mergeFormatAndEncoding(
+      newTarget[encodedFieldName],
       encodeData.encoding,
       newType.format,
     );

packages/openapi3/src/json-schema.ts

@@ -0,0 +1,9 @@
+export type JsonSchemaModule = typeof import("@typespec/json-schema");
+
+export async function resolveJsonSchemaModule(): Promise<JsonSchemaModule | undefined> {
+  try {
+    return await import("@typespec/json-schema");
+  } catch {
+    return undefined;
+  }
+}

packages/openapi3/src/lib.ts

@@ -1,6 +1,7 @@
 import { createTypeSpecLibrary, JSONSchemaType, paramMessage } from "@typespec/compiler";
 
 export type FileType = "yaml" | "json";
+export type OpenAPIVersion = "3.0.0" | "3.1.0";
 export interface OpenAPI3EmitterOptions {
   /**
    * If the content should be serialized as YAML or JSON.
@@ -36,6 +37,16 @@ export interface OpenAPI3EmitterOptions {
    */
   "output-file"?: string;
 
+  /**
+   * The Open API specification versions to emit.
+   * If more than one version is specified, then the output file
+   * will be created inside a directory matching each specification version.
+   *
+   * @default ["v3.0"]
+   * @internal
+   */
+  "openapi-versions"?: OpenAPIVersion[];
+
   /**
    * Set the newline character for emitting files.
    * @default lf
@@ -104,6 +115,18 @@ const EmitterOptionsSchema: JSONSchemaType<OpenAPI3EmitterOptions> = {
         "  - `openapi.Org1.Service2.v1.1.yaml`    ",
       ].join("\n"),
     },
+    "openapi-versions": {
+      type: "array",
+      items: {
+        type: "string",
+        enum: ["3.0.0", "3.1.0"],
+        nullable: true,
+        description: "The versions of OpenAPI to emit. Defaults to `[3.0.0]`",
+      },
+      nullable: true,
+      uniqueItems: true,
+      minItems: 1,
+    },
     "new-line": {
       type: "string",
       enum: ["crlf", "lf"],

packages/openapi3/src/openapi-helpers-3-0.ts

@@ -0,0 +1,25 @@
+import { applyEncoding as baseApplyEncoding } from "./encoding.js";
+import { OpenApiSpecSpecificProps } from "./openapi-spec-mappings.js";
+import { OpenAPI3Schema } from "./types.js";
+
+function getEncodingFieldName() {
+  // In Open API 3.0, format is always used for encoding.
+  return "format";
+}
+
+export const applyEncoding: OpenApiSpecSpecificProps["applyEncoding"] = (
+  program,
+  typespecType,
+  target,
+  options,
+) => {
+  return baseApplyEncoding(program, typespecType, target, getEncodingFieldName, options);
+};
+
+export const getRawBinarySchema = (): OpenAPI3Schema => {
+  return { type: "string", format: "binary" };
+};
+
+export const isRawBinarySchema = (schema: OpenAPI3Schema): boolean => {
+  return schema.type === "string" && schema.format === "binary";
+};

packages/openapi3/src/openapi-helpers-3-1.ts

@@ -0,0 +1,36 @@
+import { ModelProperty, Scalar } from "@typespec/compiler";
+import { applyEncoding as baseApplyEncoding } from "./encoding.js";
+import { OpenApiSpecSpecificProps } from "./openapi-spec-mappings.js";
+import { OpenAPISchema3_1 } from "./types.js";
+import { isScalarExtendsBytes } from "./util.js";
+
+function getEncodingFieldName(typespecType: Scalar | ModelProperty) {
+  // In Open API 3.1, `contentEncoding` is used for encoded binary data instead of `format`.
+  const typeIsBytes = isScalarExtendsBytes(
+    typespecType.kind === "ModelProperty" ? typespecType.type : typespecType,
+  );
+  if (typeIsBytes) {
+    return "contentEncoding";
+  }
+  return "format";
+}
+
+export const applyEncoding: OpenApiSpecSpecificProps["applyEncoding"] = (
+  program,
+  typespecType,
+  target,
+  options,
+) => {
+  return baseApplyEncoding(program, typespecType, target, getEncodingFieldName, options);
+};
+
+export const getRawBinarySchema = (contentType?: string): OpenAPISchema3_1 => {
+  if (contentType) {
+    return { contentMediaType: contentType };
+  }
+  return {};
+};
+
+export const isRawBinarySchema = (schema: OpenAPISchema3_1): boolean => {
+  return schema.type === undefined;
+};

packages/openapi3/src/openapi-spec-mappings.ts

@@ -0,0 +1,109 @@
+import { EmitContext, ModelProperty, Namespace, Program, Scalar } from "@typespec/compiler";
+import { AssetEmitter } from "@typespec/compiler/emitter-framework";
+import { MetadataInfo } from "@typespec/http";
+import { getExternalDocs, resolveInfo } from "@typespec/openapi";
+import { JsonSchemaModule } from "./json-schema.js";
+import { OpenAPI3EmitterOptions, OpenAPIVersion } from "./lib.js";
+import {
+  applyEncoding as applyEncoding3_0,
+  getRawBinarySchema as getRawBinarySchema3_0,
+  isRawBinarySchema as isRawBinarySchema3_0,
+} from "./openapi-helpers-3-0.js";
+import {
+  applyEncoding as applyEncoding3_1,
+  getRawBinarySchema as getRawBinarySchema3_1,
+  isRawBinarySchema as isRawBinarySchema3_1,
+} from "./openapi-helpers-3-1.js";
+import { ResolvedOpenAPI3EmitterOptions } from "./openapi.js";
+import { createSchemaEmitter3_0 } from "./schema-emitter-3-0.js";
+import { createSchemaEmitter3_1 } from "./schema-emitter-3-1.js";
+import { OpenAPI3Schema, OpenAPISchema3_1, SupportedOpenAPIDocuments } from "./types.js";
+import { VisibilityUsageTracker } from "./visibility-usage.js";
+import { XmlModule } from "./xml-module.js";
+
+export type CreateSchemaEmitter = (props: {
+  program: Program;
+  context: EmitContext<OpenAPI3EmitterOptions>;
+  metadataInfo: MetadataInfo;
+  visibilityUsage: VisibilityUsageTracker;
+  options: ResolvedOpenAPI3EmitterOptions;
+  optionalDependencies: { jsonSchemaModule?: JsonSchemaModule; xmlModule?: XmlModule };
+}) => AssetEmitter<OpenAPI3Schema | OpenAPISchema3_1, OpenAPI3EmitterOptions>;
+
+export interface OpenApiSpecSpecificProps {
+  applyEncoding(
+    program: Program,
+    typespecType: Scalar | ModelProperty,
+    target: OpenAPI3Schema,
+    options: ResolvedOpenAPI3EmitterOptions,
+  ): OpenAPI3Schema & OpenAPISchema3_1;
+  createRootDoc: (
+    program: Program,
+    serviceType: Namespace,
+    serviceVersion?: string,
+  ) => SupportedOpenAPIDocuments;
+
+  createSchemaEmitter: CreateSchemaEmitter;
+  /**
+   * Returns the binary description for an unencoded binary type
+   * @see https://spec.openapis.org/oas/v3.1.1.html#migrating-binary-descriptions-from-oas-3-0
+   */
+  getRawBinarySchema(contentType?: string): OpenAPI3Schema | OpenAPISchema3_1;
+
+  isRawBinarySchema(schema: OpenAPI3Schema | OpenAPISchema3_1): boolean;
+}
+
+export function getOpenApiSpecProps(specVersion: OpenAPIVersion): OpenApiSpecSpecificProps {
+  switch (specVersion) {
+    case "3.0.0":
+      return {
+        applyEncoding: applyEncoding3_0,
+        createRootDoc(program, serviceType, serviceVersion) {
+          return createRoot(program, serviceType, specVersion, serviceVersion);
+        },
+        createSchemaEmitter: createSchemaEmitter3_0,
+        getRawBinarySchema: getRawBinarySchema3_0,
+        isRawBinarySchema: isRawBinarySchema3_0,
+      };
+    case "3.1.0":
+      return {
+        applyEncoding: applyEncoding3_1,
+        createRootDoc(program, serviceType, serviceVersion) {
+          return createRoot(program, serviceType, specVersion, serviceVersion);
+        },
+        createSchemaEmitter: createSchemaEmitter3_1,
+        getRawBinarySchema: getRawBinarySchema3_1,
+        isRawBinarySchema: isRawBinarySchema3_1,
+      };
+  }
+}
+
+function createRoot(
+  program: Program,
+  serviceType: Namespace,
+  specVersion: OpenAPIVersion,
+  serviceVersion?: string,
+): SupportedOpenAPIDocuments {
+  const info = resolveInfo(program, serviceType);
+
+  return {
+    openapi: specVersion,
+    info: {
+      title: "(title)",
+      ...info,
+      version: serviceVersion ?? info?.version ?? "0.0.0",
+    },
+    externalDocs: getExternalDocs(program, serviceType),
+    tags: [],
+    paths: {},
+    security: undefined,
+    components: {
+      parameters: {},
+      requestBodies: {},
+      responses: {},
+      schemas: {},
+      examples: {},
+      securitySchemes: {},
+    },
+  };
+}