Add xml support to openapi3 (#4214)

1. add test cases based on
[Examples](https://tspwebsitepr.z22.web.core.windows.net/prs/2982/docs/next/release-notes/xml-support.html#examples)
2. add xml in OpenAPI3Schema type
3. update schema-emitter logic for support xml object

---------

Co-authored-by: Kyle Zhang <[email protected]>
Co-authored-by: Timothee Guerin <[email protected]>
Co-authored-by: Wanpeng Li <[email protected]>

Author: 4 people

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

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add XML support using `@typespec/xml` library

.gitignore

@@ -48,6 +48,7 @@ coverage.xml
 .pytest_cache/
 test-results.xml
 test-results/
+__snapshots__/
 
 # Translations
 *.mo
@@ -224,4 +225,3 @@ BenchmarkDotnet.Artifacts/
 packages/http-client-python/generator/test/**/generated/
 packages/http-client-python/generator/test/**/cadl-ranch-coverage.json
 !packages/http-client-python/package-lock.json
-

packages/openapi3/package.json

@@ -67,6 +67,11 @@
     "@typespec/openapi": "workspace:~",
     "@typespec/versioning": "workspace:~"
   },
+  "peerDependenciesMeta": {
+    "@typespec/xml": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "~22.7.5",
     "@types/yargs": "~17.0.33",
@@ -77,6 +82,7 @@
     "@typespec/rest": "workspace:~",
     "@typespec/tspd": "workspace:~",
     "@typespec/versioning": "workspace:~",
+    "@typespec/xml": "workspace:~",
     "@vitest/coverage-v8": "^2.1.2",
     "@vitest/ui": "^2.1.2",
     "c8": "^10.1.2",

packages/openapi3/src/lib.ts

@@ -263,6 +263,18 @@ export const libDef = {
         default: paramMessage`Authentication "${"authType"}" is not a known authentication by the openapi3 emitter, it will be ignored.`,
       },
     },
+    "xml-attribute-invalid-property-type": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`XML \`@attribute\` can only be primitive types in the OpenAPI 3 emitter, Property '${"name"}' type will be changed to type: string.`,
+      },
+    },
+    "xml-unwrapped-invalid-property-type": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`XML \`@unwrapped\` can only used on array properties or primitive ones in the OpenAPI 3 emitter, Property '${"name"}' will be ignored.`,
+      },
+    },
   },
   emitter: {
     options: EmitterOptionsSchema as JSONSchemaType<OpenAPI3EmitterOptions>,

packages/openapi3/src/openapi.ts

@@ -113,6 +113,7 @@ import {
 } from "./types.js";
 import { deepEquals, isSharedHttpOperation, SharedHttpOperation } from "./util.js";
 import { resolveVisibilityUsage, VisibilityUsageTracker } from "./visibility-usage.js";
+import { resolveXmlModule, XmlModule } from "./xml-module.js";
 
 const defaultFileType: FileType = "yaml";
 const defaultOptions = {
@@ -284,6 +285,7 @@ function createOAPIEmitter(
     service: Service,
     allHttpAuthentications: HttpAuth[],
     defaultAuth: AuthenticationReference,
+    xmlModule: XmlModule | undefined,
     version?: string,
   ) {
     diagnostics = createDiagnosticCollector();
@@ -298,11 +300,12 @@ function createOAPIEmitter(
       service.type,
       options.omitUnreachableTypes,
     );
+
     schemaEmitter = createAssetEmitter(
       program,
       class extends OpenAPI3SchemaEmitter {
         constructor(emitter: AssetEmitter<Record<string, any>, OpenAPI3EmitterOptions>) {
-          super(emitter, metadataInfo, visibilityUsage, options);
+          super(emitter, metadataInfo, visibilityUsage, options, xmlModule);
         }
       } as any,
       context,
@@ -615,7 +618,8 @@ function createOAPIEmitter(
       const httpService = ignoreDiagnostics(getHttpService(program, service.type));
       const auth = (serviceAuth = resolveAuthentication(httpService));
 
-      initializeEmitter(service, auth.schemes, auth.defaultAuth, version);
+      const xmlModule = await resolveXmlModule();
+      initializeEmitter(service, auth.schemes, auth.defaultAuth, xmlModule, version);
       reportIfNoRoutes(program, httpService.operations);
 
       for (const op of resolveOperations(httpService.operations)) {

packages/openapi3/src/schema-emitter.ts

@@ -84,6 +84,7 @@ import {
   OpenAPI3SchemaProperty,
 } from "./types.js";
 import { VisibilityUsageTracker } from "./visibility-usage.js";
+import { XmlModule } from "./xml-module.js";
 
 /**
  * OpenAPI3 schema emitter. Deals with emitting content of `components/schemas` section.
@@ -95,16 +96,19 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
   #metadataInfo: MetadataInfo;
   #visibilityUsage: VisibilityUsageTracker;
   #options: ResolvedOpenAPI3EmitterOptions;
+  #xmlModule: XmlModule | undefined;
   constructor(
     emitter: AssetEmitter<Record<string, any>, OpenAPI3EmitterOptions>,
     metadataInfo: MetadataInfo,
     visibilityUsage: VisibilityUsageTracker,
     options: ResolvedOpenAPI3EmitterOptions,
+    xmlModule: XmlModule | undefined,
   ) {
     super(emitter);
     this.#metadataInfo = metadataInfo;
     this.#visibilityUsage = visibilityUsage;
     this.#options = options;
+    this.#xmlModule = xmlModule;
   }
 
   modelDeclarationReferenceContext(model: Model, name: string): Context {
@@ -382,7 +386,7 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
     const schema = this.#applyEncoding(prop, refSchema.value as any);
 
     // Apply decorators on the property to the type's schema
-    const additionalProps: Partial<OpenAPI3Schema> = this.#applyConstraints(prop, {});
+    const additionalProps: Partial<OpenAPI3Schema> = this.#applyConstraints(prop, {}, schema);
     if (prop.defaultValue) {
       additionalProps.default = getDefaultValue(program, prop.defaultValue, prop);
     }
@@ -398,10 +402,14 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
       if (Object.keys(additionalProps).length === 0) {
         return schema;
       } else {
-        return {
-          allOf: [schema],
-          ...additionalProps,
-        };
+        if (additionalProps.xml?.attribute) {
+          return additionalProps;
+        } else {
+          return {
+            allOf: [schema],
+            ...additionalProps,
+          };
+        }
       }
     } else {
       if (getOneOf(program, prop) && schema.anyOf) {
@@ -765,6 +773,7 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
   #applyConstraints(
     type: Scalar | Model | ModelProperty | Union | Enum,
     original: OpenAPI3Schema,
+    refSchema?: OpenAPI3Schema,
   ): ObjectBuilder<OpenAPI3Schema> {
     const schema = new ObjectBuilder(original);
     const program = this.emitter.getProgram();
@@ -813,6 +822,24 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
       "deprecated",
     );
 
+    if (this.#xmlModule) {
+      switch (type.kind) {
+        case "Scalar":
+        case "Model":
+          this.#xmlModule.attachXmlObjectForScalarOrModel(program, type, schema);
+          break;
+        case "ModelProperty":
+          this.#xmlModule.attachXmlObjectForModelProperty(
+            program,
+            this.#options,
+            type,
+            schema,
+            refSchema,
+          );
+          break;
+      }
+    }
+
     this.#attachExtensions(program, type, schema);
 
     const values = getKnownValues(program, type as any);

packages/openapi3/src/types.ts

@@ -376,6 +376,14 @@ 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 +595,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?: OpenAPI3XmlSchema;
 };
 
 export type OpenAPI3ParameterBase = Extensions & {