updating to honor original spec format

Author: EMaher

src/clients/apim-client.ts

@@ -7,7 +7,7 @@
  */
 
 import { DefaultAzureCredential } from '@azure/identity';
-import { IApimClient } from './iapim-client.js';
+import { IApimClient, ApiSpecDialect } from './iapim-client.js';
 import { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
 import { RESOURCE_TYPE_METADATA, ResourceType } from '../models/resource-types.js';
 import { buildArmUri, buildResourceLabel } from '../lib/resource-uri.js';
@@ -493,9 +493,10 @@ export class ApimClient implements IApimClient {
   async getApiSpecification(
     context: ApimServiceContext,
     apiName: string,
-    apiType?: string
+    apiType?: string,
+    specDialect?: ApiSpecDialect
   ): Promise<{ content: string; format: 'yaml' | 'json' | 'graphql' | 'wsdl' | 'wadl' } | undefined> {
-    const exportFormat = this.getExportFormat(apiType);
+    const exportFormat = this.getExportFormat(apiType, specDialect);
     if (exportFormat === undefined) {
       return undefined;
     }
@@ -667,23 +668,29 @@ export class ApimClient implements IApimClient {
    * round-tripping is preserved even when the link variant is broken.
    *
    * Additional export formats supported by APIM for type=http REST APIs:
-   *   swagger-link          – Swagger 2.0 YAML
+   *   swagger-link          – Swagger 2.0 JSON
    *   openapi+json-link     – OpenAPI 3.0 JSON
    *   wadl-link             – WADL
    * These cannot be auto-selected from properties.type alone because all REST APIs
    * (whether originally imported as Swagger 2.0, OpenAPI 3.0, or WADL) share
-   * type=http in APIM. openapi-link is used as the preferred modern default.
+   * type=http in APIM. The caller passes `specDialect` so the export format
+   * matches the API's native source format: 'swagger2' exports via `swagger-link`,
+   * 'openapi3' (default) via `openapi-link`. This preserves the original format
+   * (and its schema/operation metadata) instead of converting Swagger 2.0 to
+   * OpenAPI 3.0 on export.
    *
    * Returns undefined for WebSocket APIs — they have no traditional API specification.
    * getApiSpecification will return undefined early when this method returns undefined.
    */
-  private getExportFormat(apiType?: string): string | undefined {
+  private getExportFormat(apiType?: string, specDialect?: ApiSpecDialect): string | undefined {
     switch (apiType?.toLowerCase()) {
       case 'graphql':   return 'graphql-link';
       case 'soap':      return 'wsdl-link';
       case 'websocket': return undefined;
       case 'a2a':       return undefined;
-      default:          return 'openapi-link';
+      // REST (http / odata / grpc / undefined): match the source dialect —
+      // export Swagger 2.0 when the API was natively Swagger 2.0, else OpenAPI 3.0.
+      default:          return specDialect === 'swagger2' ? 'swagger-link' : 'openapi-link';
     }
   }
 

src/clients/iapim-client.ts

@@ -8,6 +8,16 @@
 import { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
 import { ResourceType } from '../models/resource-types.js';
 
+/**
+ * Spec dialect for a REST (type=http) API. Both dialects share APIM's
+ * `type=http`, so the dialect is an orthogonal axis to {@link ResourceType}/
+ * `apiType` and is detected from the API's schema content type rather than
+ * stored on the resource type.
+ *   - 'openapi3': OpenAPI 3.x
+ *   - 'swagger2': Swagger / OpenAPI 2.0
+ */
+export type ApiSpecDialect = 'openapi3' | 'swagger2';
+
 export interface IApimClient {
   /**
    * List all resources of a given type. Handles ARM pagination (nextLink).
@@ -74,11 +84,15 @@ export interface IApimClient {
    * Returns the raw content string and detected format.
    * @param apiType - Optional API type from properties.type (e.g. 'graphql', 'soap', 'http').
    *   Used to select the correct APIM export format. Defaults to OpenAPI link export.
+   * @param specDialect - For a REST (http) API, the spec dialect to export so the
+   *   exported spec matches the API's native source format: 'swagger2' exports via
+   *   `swagger-link`, 'openapi3' (default) via `openapi-link`.
    */
   getApiSpecification(
     context: ApimServiceContext,
     apiName: string,
-    apiType?: string
+    apiType?: string,
+    specDialect?: ApiSpecDialect
   ): Promise<
     | { content: string; format: 'yaml' | 'json' | 'graphql' | 'wsdl' | 'wadl' }
     | undefined

src/services/api-extractor.ts

@@ -7,7 +7,7 @@
  * releases, tag descriptions, wikis.
  */
 
-import { IApimClient } from '../clients/iapim-client.js';
+import { IApimClient, ApiSpecDialect } from '../clients/iapim-client.js';
 import { IArtifactStore } from '../clients/iartifact-store.js';
 import { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
 import { ResourceType, RESOURCE_TYPE_METADATA } from '../models/resource-types.js';
@@ -380,8 +380,17 @@ async function extractApiSpecification(
     return false;
   }
 
+  // REST APIs natively imported as Swagger 2.0 expose auto-generated schemas
+  // with the Swagger-definitions content type. Export them in their native
+  // dialect so the exported spec matches the API's source format (OpenAPI 3.0
+  // export would convert schema content types and drop parameter-level metadata
+  // like `format`).
+  const specDialect: ApiSpecDialect = hasSwaggerDefinitionSchema(extractedSchemas)
+    ? 'swagger2'
+    : 'openapi3';
+
   try {
-    const spec = await client.getApiSpecification(context, getNamePart(apiDescriptor.nameParts, 0), apiType);
+    const spec = await client.getApiSpecification(context, getNamePart(apiDescriptor.nameParts, 0), apiType, specDialect);
     if (!spec) {
       logger.debug(`No specification found for API "${getNamePart(apiDescriptor.nameParts, 0)}"`);
       return false;
@@ -422,6 +431,25 @@ function hasGraphQLSchema(schemas: ExtractedResource[]): boolean {
   return false;
 }
 
+/**
+ * Returns true if any already-extracted ApiSchema resource has the Swagger 2.0
+ * definitions content type (`application/vnd.ms-azure-apim.swagger.definitions+json`).
+ * APIM stamps this content type on the auto-generated schema of APIs that were
+ * natively imported as Swagger 2.0, whereas OpenAPI 3.0 APIs use
+ * `application/vnd.oai.openapi.components+json`. Used to select Swagger 2.0
+ * export so the original spec format round-trips faithfully.
+ */
+function hasSwaggerDefinitionSchema(schemas: ExtractedResource[]): boolean {
+  for (const schema of schemas) {
+    const props = schema.json.properties as Record<string, unknown> | undefined;
+    const contentType = (props?.contentType as string | undefined)?.toLowerCase() ?? '';
+    if (contentType.includes('swagger.definitions')) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Extract API-level policy.
  */

src/services/api-publisher.ts

@@ -7,7 +7,7 @@
  * Handle SOAP/WSDL import via ?import=true&format=wsdl-link query parameter.
  */
 
-import type { IApimClient } from '../clients/iapim-client.js';
+import type { IApimClient, ApiSpecDialect } from '../clients/iapim-client.js';
 import type { IArtifactStore } from '../clients/iartifact-store.js';
 import type { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
 import type { PublishConfig } from '../models/config.js';
@@ -105,8 +105,11 @@ export async function publishApi(
 
 /**
  * Maps spec file format to APIM ContentFormat for inline import.
+ * @param specDialect - The spec dialect of a JSON spec. Swagger 2.0 ('swagger2')
+ *   must be imported via `swagger-json` so its native format (and schema/operation
+ *   metadata) is preserved; OpenAPI 3.x ('openapi3') uses `openapi+json`.
  */
-function getImportFormat(specFormat: string, _apiType?: string): string | undefined {
+function getImportFormat(specFormat: string, _apiType?: string, specDialect?: ApiSpecDialect): string | undefined {
   const apiType = _apiType?.toLowerCase();
   if (apiType === 'a2a') {
     return undefined;
@@ -116,9 +119,10 @@ function getImportFormat(specFormat: string, _apiType?: string): string | undefi
     case 'yaml':
       return 'openapi';
     case 'json':
-      // Swagger 2.0 uses swagger-json, OpenAPI 3.x uses openapi+json.
-      // Default to openapi+json as the more modern format — APIM accepts both.
-      return 'openapi+json';
+      // Match the source dialect: Swagger 2.0 uses swagger-json, OpenAPI 3.x uses
+      // openapi+json. APIM accepts both, but importing a Swagger 2.0 document as
+      // openapi+json would convert it to OpenAPI 3.0 and lose fidelity.
+      return specDialect === 'swagger2' ? 'swagger-json' : 'openapi+json';
     case 'wsdl':
       return 'wsdl';
     case 'wadl':
@@ -181,7 +185,8 @@ async function publishRootApi(
   if (specResult) {
     const properties = json.properties as Record<string, unknown> | undefined;
     const apiType = properties?.type as string | undefined;
-    const importFormat = getImportFormat(specResult.format ?? 'yaml', apiType);
+    const specDialect = detectSpecDialect(specResult.content, specResult.format);
+    const importFormat = getImportFormat(specResult.format ?? 'yaml', apiType, specDialect);
 
     if (importFormat) {
       // Strip null-valued properties that cause validation errors in
@@ -213,7 +218,7 @@ async function publishRootApi(
         },
       };
 
-      if (importFormat === 'openapi' || importFormat === 'openapi+json') {
+      if (importFormat === 'openapi' || importFormat === 'openapi+json' || importFormat === 'swagger-json') {
         operationIdsWithNullDescription = getOpenApiOperationIdsWithNullDescription(
           specResult.content,
           specResult.format
@@ -609,14 +614,36 @@ function getOpenApiOperationIdsWithNullDescription(
   }
 }
 
+/**
+ * Detects the spec dialect of a JSON spec document. Returns 'swagger2' when the
+ * content is a Swagger 2.0 JSON document (top-level `"swagger": "2.0"`),
+ * otherwise 'openapi3'. Only JSON specs are inspected because APIM's Swagger 2.0
+ * inline import (`swagger-json`) accepts JSON only; YAML specs are treated as
+ * OpenAPI 3.x.
+ */
+function detectSpecDialect(content: string, format: string | undefined): ApiSpecDialect {
+  const isJson =
+    !format ||
+    format.toLowerCase().includes('json') ||
+    content.trimStart().startsWith('{');
+  if (!isJson) return 'openapi3';
+  try {
+    const spec = JSON.parse(content) as Record<string, unknown>;
+    return spec.swagger === '2.0' ? 'swagger2' : 'openapi3';
+  } catch {
+    return 'openapi3';
+  }
+}
+
 /**
  * Sanitize an OpenAPI spec before importing into APIM.
  * Currently handles:
  *  - Missing path parameter declarations: APIM rejects specs where a URL
  *    template contains `{param}` placeholders that are not declared in the
  *    operation's `parameters` array.  We auto-inject the missing declarations
- *    as `{ name, in: "path", required: true, schema: { type: "string" } }`
- *    and log a warning for each one.
+ *    using the document's native parameter shape — OpenAPI 3.x uses
+ *    `{ ..., schema: { type: "string" } }` while Swagger 2.0 uses
+ *    `{ ..., type: "string" }` — and log a warning for each one.
  */
 function sanitizeOpenApiSpec(
   content: string,
@@ -637,6 +664,11 @@ function sanitizeOpenApiSpec(
     return content; // Not valid JSON — return as-is
   }
 
+  // Swagger 2.0 path parameters are declared inline (`type: string`) rather
+  // than wrapped in a `schema` object as in OpenAPI 3.x. Inject the matching
+  // shape so the document stays valid for its native import format.
+  const isSwagger2 = spec.swagger === '2.0';
+
   const paths = spec.paths as Record<string, Record<string, unknown>> | undefined;
   if (!paths) return content;
 
@@ -664,13 +696,11 @@ function sanitizeOpenApiSpec(
 
       for (const name of placeholderNames) {
         if (!declaredPathParams.has(name)) {
-          // Inject the missing parameter declaration
-          const newParam: Record<string, unknown> = {
-            name,
-            in: 'path',
-            required: true,
-            schema: { type: 'string' },
-          };
+          // Inject the missing parameter declaration using the document's
+          // native parameter shape (Swagger 2.0 vs OpenAPI 3.x).
+          const newParam: Record<string, unknown> = isSwagger2
+            ? { name, in: 'path', required: true, type: 'string' }
+            : { name, in: 'path', required: true, schema: { type: 'string' } };
           const updatedParams = [...params, newParam];
           op.parameters = updatedParams;
           // Update params reference for subsequent placeholder checks on this operation

tests/unit/clients/apim-client.test.ts

@@ -1146,6 +1146,51 @@ describe('ApimClient.getApiSpecification', () => {
     expect(apimCallUrl).toContain('format=openapi-link');
   });
 
+  it('should use swagger-link format when source dialect is swagger2', async () => {
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ value: {} }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+
+    await client.getApiSpecification(testContext, 'rest-api', 'http', 'swagger2');
+
+    const apimCallUrl = fetchSpy.mock.calls[0][0] as string;
+    expect(apimCallUrl).toContain('format=swagger-link');
+    expect(apimCallUrl).not.toContain('format=openapi-link');
+  });
+
+  it('should still use openapi-link when source dialect is openapi3', async () => {
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ value: {} }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+
+    await client.getApiSpecification(testContext, 'rest-api', 'http', 'openapi3');
+
+    const apimCallUrl = fetchSpy.mock.calls[0][0] as string;
+    expect(apimCallUrl).toContain('format=openapi-link');
+    expect(apimCallUrl).not.toContain('format=swagger-link');
+  });
+
+  it('should ignore specDialect for non-REST apiTypes (graphql stays graphql-link)', async () => {
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ value: {} }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+
+    await client.getApiSpecification(testContext, 'gql-api', 'graphql', 'swagger2');
+
+    const apimCallUrl = fetchSpy.mock.calls[0][0] as string;
+    expect(apimCallUrl).toContain('format=graphql-link');
+    expect(apimCallUrl).not.toContain('format=swagger-link');
+  });
+
   it('should return undefined for websocket apiType without making an HTTP request', async () => {
     // WebSocket APIs have no traditional API specification. getExportFormat returns
     // undefined for websocket, causing getApiSpecification to short-circuit.

tests/unit/services/api-product-extractor.test.ts

@@ -190,7 +190,7 @@ describe('api-extractor', () => {
       );
 
       expect(result.specification).toBe(true);
-      expect(getApiSpecification).toHaveBeenCalledWith(testContext, 'linked-gql', 'graphql');
+      expect(getApiSpecification).toHaveBeenCalledWith(testContext, 'linked-gql', 'graphql', 'openapi3');
       expect(store.writeContent).toHaveBeenCalledWith(
         '/output',
         expect.objectContaining({ nameParts: ['linked-gql'] }),
@@ -200,6 +200,67 @@ describe('api-extractor', () => {
       );
     });
 
+    it('should export the swagger2 dialect when the API has a Swagger-definitions schema', async () => {
+      const getApiSpecification = vi.fn().mockResolvedValue({
+        content: '{"swagger":"2.0"}',
+        format: 'json',
+      });
+      const client = createMockClient({
+        getApiSpecification,
+        // Yield a Swagger 2.0 auto-generated schema for the ApiSchema list step
+        listResources: async function* (_ctx: ApimServiceContext, type: ResourceType) {
+          if (type === ResourceType.ApiSchema) {
+            yield {
+              name: 'swagger-defs',
+              properties: { contentType: 'application/vnd.ms-azure-apim.swagger.definitions+json' },
+            };
+          }
+        },
+        getResource: vi.fn().mockResolvedValue(undefined),
+      });
+      const store = createMockStore();
+
+      const result = await extractApiResources(
+        client, store, testContext,
+        { type: ResourceType.Api, nameParts: ['swagger-rest'] },
+        { name: 'swagger-rest', properties: { type: 'http' } },
+        '/output'
+      );
+
+      expect(result.specification).toBe(true);
+      expect(getApiSpecification).toHaveBeenCalledWith(testContext, 'swagger-rest', 'http', 'swagger2');
+    });
+
+    it('should export the openapi3 dialect when the API has an OpenAPI components schema', async () => {
+      const getApiSpecification = vi.fn().mockResolvedValue({
+        content: '{"openapi":"3.0.1"}',
+        format: 'json',
+      });
+      const client = createMockClient({
+        getApiSpecification,
+        listResources: async function* (_ctx: ApimServiceContext, type: ResourceType) {
+          if (type === ResourceType.ApiSchema) {
+            yield {
+              name: 'openapi-defs',
+              properties: { contentType: 'application/vnd.oai.openapi.components+json' },
+            };
+          }
+        },
+        getResource: vi.fn().mockResolvedValue(undefined),
+      });
+      const store = createMockStore();
+
+      const result = await extractApiResources(
+        client, store, testContext,
+        { type: ResourceType.Api, nameParts: ['openapi-rest'] },
+        { name: 'openapi-rest', properties: { type: 'http' } },
+        '/output'
+      );
+
+      expect(result.specification).toBe(true);
+      expect(getApiSpecification).toHaveBeenCalledWith(testContext, 'openapi-rest', 'http', 'openapi3');
+    });
+
     it('should extract API policy and collect content', async () => {
       const policyContent = '<policies><inbound><base /></inbound></policies>';
       const client = createMockClient({