feat: update all-types round-trip test to import Petstore Swagger (V2 and V3) (#171)

* feat: update all-types test to use petstore swagger (v2 and v3)
- updating to honor original spec format of imported spec
* Enhance round-trip comparison by refining ignored properties for API imports

Closes #170

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Elizabeth Maher <enewman@microsoft.com>

Author: Copilot

.squad/agents/apimexpert/history.md

@@ -106,3 +106,13 @@ the SDK surface, reference docs, or ad-hoc observation.
 - Classic Developer/Premium SKU only.
 - Docs: <https://learn.microsoft.com/rest/api/apimanagement/policy-restriction> · <https://learn.microsoft.com/azure/templates/microsoft.apimanagement/service/policyrestrictions>
 
+### 2026-06-20: Link-import vs inline-import operation fidelity (round-trip)
+
+When comparing a *link-imported* API (e.g. Petstore via `swagger-link`/`openapi-link`) against the `apiops publish` *inline-imported* result, operation payloads diverge in two import-path-only ways — neither is an apiops bug:
+
+1. **`schemaId`/`typeName` on representations.** APIM binds operation request/response representations to an API-level schema **only on link import**. Inline import (`format: openapi, value: <spec>`, what publish uses) does NOT rebind, so the target has no `schemaId`. The schema *content* is identical and still extracted as API-level Schemas. → strip `schemaId`, `typeName` (and any derived schema token) on operation resources.
+
+2. **Parameter/header `description`.** Link import drops `templateParameters`/`queryParameters`/header descriptions; inline import preserves them from the spec. So the published **target is more faithful** than the link-imported source. Authoritative descriptions live in the API schema. → strip `description` on parameter-shaped objects (`{ name, …, values }`).
+
+Round-trip comparison harness (`tests/integration/all-resource-types`) normalizes both via `RepresentationSchemaRefIgnoredProperties` and `ParameterIgnoredProperties`. Symptom if not stripped: every operation shows a `properties.request/responses/templateParameters` DIFF present-on-one-side-only.
+

.squad/decisions/decisions.md

@@ -117,3 +117,18 @@ All new `.ts` files in `src/` and `tests/` must include:
 **Constitution compliance:** §I, §III, §IV, §V, §VI, §VII, §VIII
 
 ---
+
+### 2026-06-19: Spec dialect (Swagger 2.0 vs OpenAPI 3.0) is orthogonal to APIM `apiType`
+**By:** CodeReviewer  
+**Status:** Approved  
+**Context:** Round-trip extract→publish produced diffs on a natively Swagger 2.0 REST API.  
+**Learned:**
+- APIM's `properties.type` (`http`/`soap`/`graphql`/…) does **not** encode spec dialect — both Swagger 2.0 and OpenAPI 3.0 REST APIs are `type=http`. Dialect is a separate axis and must be detected, not inferred from type.
+- Detect dialect from the auto-generated schema's content type: `application/vnd.ms-azure-apim.swagger.definitions+json` ⇒ Swagger 2.0, `application/vnd.oai.openapi.components+json` ⇒ OpenAPI 3.0. (Spec body itself: top-level `"swagger":"2.0"`.)
+- APIM's `openapi-link` export **silently converts** Swagger 2.0 → OpenAPI 3.0, dropping parameter-level metadata (e.g. `format: int64`) and rewriting schema content types — a §VII silent-data-loss trap. Fidelity requires exporting via `swagger-link` and importing via `swagger-json` (JSON only; there is no inline Swagger YAML import format).
+- Do **not** overload `apiType` with a synthetic value like `'Swagger2'`: `apiType` is a real APIM property echoed back on PUT and validated, so it must stay within the type enum. Carry dialect as its own parameter/type instead.
+- Swagger 2.0 path parameters use the inline shape `{ name, in, required, type }`; OpenAPI 3.x wraps it as `{ ..., schema: { type } }`. Any injected/sanitized params must match the document's dialect.
+**Decision:** Introduced `ApiSpecDialect = 'openapi3' | 'swagger2'` as a first-class, detected axis threaded through export and import; preferred an explicit dialect type over a boolean or an overloaded `apiType`.  
+**Constitution compliance:** §II (APIM-native formats), §VII (no silent round-trip loss)
+
+---

src/cli/extract-command.ts

@@ -3,7 +3,7 @@
 /**
  * Extract command CLI registration
  * Commander subcommand with --resource-group, --service-name, --output,
- * --filter, --no-transitive, --spec-format flags.
+ * --filter, --no-transitive flags.
  * Includes --format json: machine-readable JSON output mode.
  */
 
@@ -26,7 +26,6 @@ interface ExtractOptions {
   output: string;
   filter?: string;
   transitive: boolean;
-  specFormat?: string;
 }
 
 /**
@@ -40,7 +39,6 @@ export function createExtractCommand(): Command {
     .option('--output <dir>', 'Output directory path', './apim-artifacts')
     .option('--filter <path>', 'Filter configuration YAML file')
     .option('--no-transitive', 'Disable transitive dependency inclusion')
-    .option('--spec-format <format>', 'API specification format (openapi-v2-json, openapi-v3-json, openapi-v3-yaml)')
     .action(async (options: ExtractOptions, command: Command) => {
       const globalOpts = command.optsWithGlobals<{
         logLevel?: string;
@@ -109,7 +107,6 @@ async function executeExtract(
     outputDir: options.output,
     filter: filterConfig,
     includeTransitive: options.transitive,
-    specFormat: options.specFormat,
     logLevel: parseLogLevel(globalOpts.logLevel ?? 'info'),
   };
 

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';
@@ -503,9 +503,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;
     }
@@ -677,23 +678,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/models/config.ts

@@ -13,7 +13,6 @@ export interface ExtractConfig {
   outputDir: string;
   filter?: FilterConfig;
   includeTransitive: boolean;
-  specFormat?: string;
   logLevel: LogLevel;
   otelConfigPath?: string;
 }

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';
@@ -268,8 +268,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;
@@ -310,6 +319,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';
@@ -108,8 +108,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;
@@ -119,9 +122,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':
@@ -189,7 +193,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
@@ -221,7 +226,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
@@ -617,14 +622,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,
@@ -645,6 +672,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;
 
@@ -672,13 +704,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/integration/all-resource-types/Compare-ApimInstance.ps1

@@ -58,12 +58,19 @@ $StripTimestampProperties = @(
 $RequestResponseIgnoredProperties = @('description')
 
 # Properties ignored on representation objects (have 'contentType' or 'schemaId'):
-# - description: SOAP/WSDL import generates descriptions that vary
-# - schemaId/typeName: Operation reconciliation strips these before PATCH because
-#   APIM rebinds representation schema refs during import. Values are therefore
-#   not stable for round-trip comparison and are ignored for operation resources.
+# - description: varies by import path.
+# - schemaId/typeName: unstable schema refs APIM rebinds on import; stripped for ops.
+# - __schemaSemantic: synthetic token from Add-RepresentationSchemaSemantics. Only
+#   link-imported source gets schemaId (and thus this token); inline-imported target
+#   doesn't. Schema content is compared separately via API-level Schemas, so strip it.
 $RepresentationIgnoredProperties = @('description')
-$RepresentationSchemaRefIgnoredProperties = @('schemaId', 'typeName')
+$RepresentationSchemaRefIgnoredProperties = @('schemaId', 'typeName', '__schemaSemantic')
+
+# Properties ignored on parameter/header objects (have 'name' + 'values':
+# templateParameters, queryParameters, response headers):
+# - description: link import (source) drops them; inline import (target) keeps them.
+#   Authoritative copies live in the API schema, compared separately.
+$ParameterIgnoredProperties = @('description')
 
 # Cache of normalized API schema semantics per instance/api, keyed as:
 # "{instance}|{apiName}" => @{ schemaId => normalizedSchemaJson }
@@ -78,7 +85,8 @@ $NormalizationContext = New-CompareNormalizationContext `
     -StripTimestampProperties $StripTimestampProperties `
     -RequestResponseIgnoredProperties $RequestResponseIgnoredProperties `
     -RepresentationIgnoredProperties $RepresentationIgnoredProperties `
-    -RepresentationSchemaRefIgnoredProperties $RepresentationSchemaRefIgnoredProperties
+    -RepresentationSchemaRefIgnoredProperties $RepresentationSchemaRefIgnoredProperties `
+    -ParameterIgnoredProperties $ParameterIgnoredProperties
 
 # ── Helpers ─────────────────────────────────────────────────────────────────