Add xml support to openapi3

.chronus/changes/simple-xml-support-2024-7-23-14-23-13.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+  - "@typespec/openapi3"
+---
+
+Add xml support to openapi3

packages/compiler/src/core/index.ts

@@ -26,6 +26,9 @@ export {
   getMinValueAsNumeric,
   getMinValueExclusive,
   getMinValueExclusiveAsNumeric,
+  getXmlNs,
+  isXmlAttribute,
+  isXmlUnwrapped,
   type Discriminator,
 } from "./intrinsic-type-state.js";
 export {

packages/compiler/src/core/intrinsic-type-state.ts

@@ -9,6 +9,10 @@ function createStateSymbol(name: string) {
   return Symbol.for(`TypeSpec.${name}`);
 }
 
+function createXmlStateSymbol(name: string) {
+  return Symbol.for(`@typespec/xml/${name}`);
+}
+
 const stateKeys = {
   minValues: createStateSymbol("minValues"),
   maxValues: createStateSymbol("maxValues"),
@@ -26,6 +30,12 @@ const stateKeys = {
   discriminator: createStateSymbol("discriminator"),
 };
 
+const XmlStateKeys = {
+  attribute: createXmlStateSymbol("attribute"),
+  unwrapped: createXmlStateSymbol("unwrapped"),
+  nsDeclaration: createXmlStateSymbol("nsDeclaration"),
+};
+
 // #region @minValue
 
 export function setMinValue(program: Program, target: Type, value: Numeric): void {
@@ -150,6 +160,22 @@ export function getMaxItems(program: Program, target: Type): number | undefined
 }
 // #endregion @maxItems
 
+// #region @xml object
+export function isXmlAttribute(program: Program, target: Type): boolean {
+  return program.stateSet(XmlStateKeys.attribute).has(target);
+}
+export function isXmlUnwrapped(program: Program, target: Type): boolean {
+  return program.stateSet(XmlStateKeys.unwrapped).has(target);
+}
+export function getXmlNs(program: Program, target: Type): XmlNamespace | undefined {
+  return program.stateMap(XmlStateKeys.nsDeclaration).get(target);
+}
+export interface XmlNamespace {
+  readonly namespace: string;
+  readonly prefix: string;
+}
+// #endregion @xml object
+
 // #region doc
 
 /** @internal */

packages/openapi3/package.json

@@ -64,7 +64,8 @@
     "@typespec/compiler": "workspace:~",
     "@typespec/http": "workspace:~",
     "@typespec/openapi": "workspace:~",
-    "@typespec/versioning": "workspace:~"
+    "@typespec/versioning": "workspace:~",
+    "@typespec/xml": "workspace:~"
   },
   "devDependencies": {
     "@types/node": "~18.11.19",
@@ -76,6 +77,7 @@
     "@typespec/rest": "workspace:~",
     "@typespec/tspd": "workspace:~",
     "@typespec/versioning": "workspace:~",
+    "@typespec/xml": "workspace:~",
     "@vitest/coverage-v8": "^2.0.4",
     "@vitest/ui": "^2.0.4",
     "c8": "^10.1.2",

packages/openapi3/src/schema-emitter.ts

@@ -40,12 +40,15 @@ import {
   getPattern,
   getSummary,
   getTypeName,
+  getXmlNs,
   ignoreDiagnostics,
   isArrayModelType,
   isNeverType,
   isNullType,
   isSecret,
   isTemplateDeclaration,
+  isXmlAttribute,
+  isXmlUnwrapped,
   resolveEncodedName,
   serializeValueAsJson,
 } from "@typespec/compiler";
@@ -77,7 +80,12 @@ import { applyEncoding } from "./encoding.js";
 import { OpenAPI3EmitterOptions, reportDiagnostic } from "./lib.js";
 import { ResolvedOpenAPI3EmitterOptions } from "./openapi.js";
 import { getSchemaForStdScalars } from "./std-scalar-schemas.js";
-import { OpenAPI3Discriminator, OpenAPI3Schema, OpenAPI3SchemaProperty } from "./types.js";
+import {
+  OpenAPI3Discriminator,
+  OpenAPI3Schema,
+  OpenAPI3SchemaProperty,
+  OpenAPI3XmlSchema,
+} from "./types.js";
 import { VisibilityUsageTracker } from "./visibility-usage.js";
 
 /**
@@ -645,6 +653,50 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
     }
   }
 
+  #attachXmlObject(program: Program, prop: ModelProperty, emitObject: OpenAPI3Schema) {
+    // Attach xml object
+    const schema = new ObjectBuilder({});
+
+    // Utility function to apply constraints
+    const applyConstraint = (fn: (p: Program, t: Type) => any, key: keyof OpenAPI3XmlSchema) => {
+      const value = fn(program, prop);
+      if (value !== undefined && value !== false) {
+        schema[key] = value;
+      }
+    };
+
+    // Resolve XML name
+    const xmlName = resolveEncodedName(program, prop, "application/xml");
+
+    if (xmlName !== prop.name) {
+      schema.name = xmlName;
+    }
+
+    // Get and set XML namespace if present
+    const currNs = getXmlNs(program, prop);
+    if (currNs) {
+      schema.prefix = currNs.prefix;
+      schema.namespace = currNs.namespace;
+    }
+
+    applyConstraint(isXmlAttribute, "attribute");
+
+    // Handle array wrapping if necessary
+    if (
+      prop.type?.kind === "Model" &&
+      isArrayModelType(program, prop.type) &&
+      xmlName !== prop.name &&
+      !isXmlUnwrapped(program, prop)
+    ) {
+      schema.wrapped = true;
+    }
+
+    // Attach schema to emitObject if not empty
+    if (Object.keys(schema).length !== 0) {
+      emitObject.xml = schema;
+    }
+  }
+
   reference(
     targetDeclaration: Declaration<Record<string, unknown>>,
     pathUp: Scope<Record<string, unknown>>[],
@@ -786,6 +838,8 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
       "deprecated"
     );
 
+    this.#attachXmlObject(program, type as ModelProperty, schema);
+
     this.#attachExtensions(program, type, schema);
 
     const values = getKnownValues(program, type as any);

packages/openapi3/src/types.ts

@@ -376,6 +376,13 @@ export type JsonType = "array" | "boolean" | "integer" | "number" | "object" | "
  */
 export type OpenAPI3SchemaProperty = Ref<OpenAPI3Schema> | OpenAPI3Schema;
 
+export type OpenAPI3XmlSchema = Extensions & {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: boolean;
+  wrapped?: boolean;
+};
 export type OpenAPI3Schema = Extensions & {
   /**
    * This attribute is a string that provides a short description of the instance property.
@@ -587,6 +594,9 @@ export type OpenAPI3Schema = Extensions & {
 
   /** Specifies that a schema is deprecated and SHOULD be transitioned out of usage.Default value is false. */
   deprecated?: boolean;
+
+  /** This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. */
+  xml?: any;
 };
 
 export type OpenAPI3ParameterBase = Extensions & {

packages/openapi3/test/test-host.ts

@@ -9,6 +9,7 @@ import { HttpTestLibrary } from "@typespec/http/testing";
 import { OpenAPITestLibrary } from "@typespec/openapi/testing";
 import { RestTestLibrary } from "@typespec/rest/testing";
 import { VersioningTestLibrary } from "@typespec/versioning/testing";
+import { XmlTestLibrary } from "@typespec/xml/testing";
 import { ok } from "assert";
 import { OpenAPI3EmitterOptions } from "../src/lib.js";
 import { OpenAPI3TestLibrary } from "../src/testing/index.js";
@@ -20,6 +21,7 @@ export async function createOpenAPITestHost() {
       HttpTestLibrary,
       RestTestLibrary,
       VersioningTestLibrary,
+      XmlTestLibrary,
       OpenAPITestLibrary,
       OpenAPI3TestLibrary,
     ],
@@ -35,10 +37,12 @@ export async function createOpenAPITestRunner({
   import "@typespec/rest";
   import "@typespec/openapi";
   import "@typespec/openapi3"; 
+  import "@typespec/xml";
   ${withVersioning ? `import "@typespec/versioning"` : ""};
   using TypeSpec.Rest;
   using TypeSpec.Http;
   using TypeSpec.OpenAPI;
+  using TypeSpec.Xml;
   ${withVersioning ? "using TypeSpec.Versioning;" : ""}
 `;
   return createTestWrapper(host, {
@@ -86,9 +90,9 @@ export async function openApiFor(
   const outPath = resolveVirtualPath("{version}.openapi.json");
   host.addTypeSpecFile(
     "./main.tsp",
-    `import "@typespec/http"; import "@typespec/rest"; import "@typespec/openapi"; import "@typespec/openapi3"; ${
+    `import "@typespec/http"; import "@typespec/rest"; import "@typespec/openapi"; import "@typespec/openapi3";import "@typespec/xml"; ${
       versions ? `import "@typespec/versioning"; using TypeSpec.Versioning;` : ""
-    }using TypeSpec.Rest;using TypeSpec.Http;using TypeSpec.OpenAPI;${code}`
+    }using TypeSpec.Rest;using TypeSpec.Http;using TypeSpec.OpenAPI;using TypeSpec.Xml;${code}`
   );
   const diagnostics = await host.diagnose("./main.tsp", {
     noEmit: false,