feat(openapi3): Add paging link decorator import from x-ms-list-*-link extensions (#9627)

The OpenAPI3 importer was not generating TypeSpec paging link decorators
(`@prevLink`, `@nextLink`, `@firstLink`, `@lastLink`) when encountering
the corresponding `x-ms-list-*-link` extensions.

## Changes

- **Added `getPagingLinkDecorators()`** in `decorators.ts` to map
x-ms-list-*-link extensions to their TypeSpec paging decorators
  - Only emits decorator when extension value is `true`
  - Supports all four link types: prev, next, first, last
- **Test coverage** for all four decorator types and value validation

## Example

Given OpenAPI schema:
```yaml
WidgetList:
  properties:
    prevLink:
      type: string
      x-ms-list-prev-link: true
```

Now generates:
```typespec
model WidgetList {
  @extension("x-ms-list-prev-link", true) @prevLink prevLink: string;
}
```

The importer emits both the `@extension` decorator (preserving the
original extension) and the semantic `@prevLink` decorator (enabling
TypeSpec's paging analysis).

> [!WARNING]
>
> <details>
> <summary>Firewall rules blocked me from connecting to one or more
addresses (expand for details)</summary>
>
> #### I tried to connect to the following addresses, but was blocked by
firewall rules:
>
> - `telemetry.astro.build`
> - Triggering command:
`/home/REDACTED/work/_temp/ghcca-node/node/bin/node node
/home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js
build sh s/.b�� e/petstore --war--llmstxt node
_modules/pnpm/dist/node-gyp-bin/node import @typespecnode --production
reams/reference sh nts/�� tsc -p tsconfig.build.json dotnet
/node_modules/.bin/sh --no-emit Release ents/reference sh` (dns block)
>
> If you need me to access, download, or install something from one of
these locations, you can either:
>
> - Configure [Actions setup
steps](https://gh.io/copilot/actions-setup-steps) to set up my
environment, which run before the firewall is enabled
> - Add the appropriate URLs or hosts to the custom allowlist in this
repository's [Copilot coding agent
settings](https://github.com/microsoft/typespec/settings/copilot/coding_agent)
(admins only)
>
> </details>

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>


----

*This section details on the original issue you should resolve*

<issue_title>Add support for importing the prevLink decorator based on
the relevant OpenAPI extension</issue_title>
<issue_description>### Clear and concise description of the problem

Related microsoft/openai-openapi-pr#568

Based on the following OpenAPI description, we should get the following
TypeSpec definition imported

```yaml
openapi: 3.0.0
info:
  title: Widget Service
  version: 0.0.0
tags:
  - name: Widgets
paths:
  /widgets:
    get:
      operationId: Widgets_list
      description: List widgets
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
    post:
      operationId: Widgets_create
      description: Create a widget
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Widget'
  /widgets/{id}:
    get:
      operationId: Widgets_read
      description: Read widgets
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            readOnly: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
    patch:
      operationId: Widgets_update
      description: Update a widget
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            readOnly: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/WidgetMergePatchUpdate'
    delete:
      operationId: Widgets_delete
      description: Delete a widget
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            readOnly: true
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
  /widgets/{id}/analyze:
    post:
      operationId: Widgets_analyze
      description: Analyze a widget
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            readOnly: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            text/plain:
              schema:
                type: string
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Widget:
      type: object
      required:
        - id
        - weight
        - colo...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #9622

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/microsoft/typespec/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>
Co-authored-by: Vincent Biret <vibiret@microsoft.com>

Author: Copilot

.chronus/changes/copilot-add-import-support-prevlink-decorator-2026-1-6-17-55-25.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+importer - Add support for importing paging link decorators (`@prevLink`, `@nextLink`, `@firstLink`, `@lastLink`) based on x-ms-list-*-link OpenAPI extensions

packages/openapi3/src/cli/actions/convert/utils/decorators.ts

@@ -29,6 +29,31 @@ export function getExtensions(element: Extensions): TypeSpecDecorator[] {
 
   return decorators;
 }
+
+function getPagingLinkDecorators(schema: OpenAPI3Schema | OpenAPISchema3_1 | OpenAPISchema3_2) {
+  const decorators: TypeSpecDecorator[] = [];
+
+  // Map of x-ms-list-*-link extensions to their corresponding TypeSpec decorators
+  const linkExtensions = {
+    "x-ms-list-prev-link": "prevLink",
+    "x-ms-list-next-link": "nextLink",
+    "x-ms-list-first-link": "firstLink",
+    "x-ms-list-last-link": "lastLink",
+  } as const;
+
+  for (const [extensionKey, decoratorName] of Object.entries(linkExtensions)) {
+    const extensionValue = (schema as any)[extensionKey];
+    if (extensionValue === true) {
+      decorators.push({
+        name: decoratorName,
+        args: [],
+      });
+    }
+  }
+
+  return decorators;
+}
+
 function normalizeObjectValue(source: unknown): string | number | object | TSValue {
   if (source !== null && typeof source === "object") {
     const result = createTSValueFromObjectValue(source);
@@ -181,6 +206,9 @@ export function getDecoratorsForSchema(
 
   decorators.push(...getExtensions(schema));
 
+  // Handle x-ms-list-*-link extensions
+  decorators.push(...getPagingLinkDecorators(schema));
+
   // Handle OpenAPI 3.1 type arrays like ["integer", "null"]
   // Extract the non-null type to determine which decorators to apply
   const effectiveType = Array.isArray(schema.type)

packages/openapi3/test/tsp-openapi3/paging-links.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, it } from "vitest";
+import { expectDecorators } from "./utils/expect.js";
+import { renderTypeSpecForOpenAPI3, tspForOpenAPI3 } from "./utils/tsp-for-openapi3.js";
+
+describe("converts paging link extensions", () => {
+  it("handles x-ms-list-prev-link extension", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      schemas: {
+        WidgetList: {
+          type: "object",
+          required: ["value", "prevLink"],
+          properties: {
+            value: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+            prevLink: {
+              type: "string",
+              "x-ms-list-prev-link": true,
+            },
+          },
+        },
+      },
+    });
+
+    const widgetList = serviceNamespace.models.get("WidgetList");
+    expect(widgetList).toBeDefined();
+
+    const prevLinkProp = widgetList?.properties.get("prevLink");
+    expect(prevLinkProp).toBeDefined();
+
+    // Should have both @extension and @prevLink decorators
+    // Note: TypeSpec compiler may reorder decorators during parsing
+    expectDecorators(prevLinkProp!.decorators, [
+      { name: "prevLink", args: [] },
+      { name: "extension", args: ["x-ms-list-prev-link", true] },
+    ]);
+  });
+
+  it("handles x-ms-list-next-link extension", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      schemas: {
+        WidgetList: {
+          type: "object",
+          required: ["value", "nextLink"],
+          properties: {
+            value: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+            nextLink: {
+              type: "string",
+              "x-ms-list-next-link": true,
+            },
+          },
+        },
+      },
+    });
+
+    const widgetList = serviceNamespace.models.get("WidgetList");
+    expect(widgetList).toBeDefined();
+
+    const nextLinkProp = widgetList?.properties.get("nextLink");
+    expect(nextLinkProp).toBeDefined();
+
+    // Should have both @extension and @nextLink decorators
+    // Note: TypeSpec compiler may reorder decorators during parsing
+    expectDecorators(nextLinkProp!.decorators, [
+      { name: "nextLink", args: [] },
+      { name: "extension", args: ["x-ms-list-next-link", true] },
+    ]);
+  });
+
+  it("handles x-ms-list-first-link extension", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      schemas: {
+        WidgetList: {
+          type: "object",
+          required: ["value", "firstLink"],
+          properties: {
+            value: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+            firstLink: {
+              type: "string",
+              "x-ms-list-first-link": true,
+            },
+          },
+        },
+      },
+    });
+
+    const widgetList = serviceNamespace.models.get("WidgetList");
+    expect(widgetList).toBeDefined();
+
+    const firstLinkProp = widgetList?.properties.get("firstLink");
+    expect(firstLinkProp).toBeDefined();
+
+    // Should have both @extension and @firstLink decorators
+    // Note: TypeSpec compiler may reorder decorators during parsing
+    expectDecorators(firstLinkProp!.decorators, [
+      { name: "firstLink", args: [] },
+      { name: "extension", args: ["x-ms-list-first-link", true] },
+    ]);
+  });
+
+  it("handles x-ms-list-last-link extension", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      schemas: {
+        WidgetList: {
+          type: "object",
+          required: ["value", "lastLink"],
+          properties: {
+            value: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+            lastLink: {
+              type: "string",
+              "x-ms-list-last-link": true,
+            },
+          },
+        },
+      },
+    });
+
+    const widgetList = serviceNamespace.models.get("WidgetList");
+    expect(widgetList).toBeDefined();
+
+    const lastLinkProp = widgetList?.properties.get("lastLink");
+    expect(lastLinkProp).toBeDefined();
+
+    // Should have both @extension and @lastLink decorators
+    // Note: TypeSpec compiler may reorder decorators during parsing
+    expectDecorators(lastLinkProp!.decorators, [
+      { name: "lastLink", args: [] },
+      { name: "extension", args: ["x-ms-list-last-link", true] },
+    ]);
+  });
+
+  it("only adds link decorator when extension value is true", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      schemas: {
+        WidgetList: {
+          type: "object",
+          required: ["value", "prevLink"],
+          properties: {
+            value: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+            prevLink: {
+              type: "string",
+              "x-ms-list-prev-link": false,
+            },
+          },
+        },
+      },
+    });
+
+    const widgetList = serviceNamespace.models.get("WidgetList");
+    expect(widgetList).toBeDefined();
+
+    const prevLinkProp = widgetList?.properties.get("prevLink");
+    expect(prevLinkProp).toBeDefined();
+
+    // Should only have @extension decorator, not @prevLink
+    expectDecorators(prevLinkProp!.decorators, [
+      { name: "extension", args: ["x-ms-list-prev-link", false] },
+    ]);
+  });
+
+  it("renders TypeSpec with correct imports for prevLink", async () => {
+    const tsp = await renderTypeSpecForOpenAPI3({
+      schemas: {
+        WidgetList: {
+          type: "object",
+          required: ["value", "prevLink"],
+          properties: {
+            value: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+            prevLink: {
+              type: "string",
+              "x-ms-list-prev-link": true,
+            },
+          },
+        },
+      },
+    });
+
+    // Should import @typespec/openapi
+    expect(tsp).toContain('import "@typespec/openapi";');
+    // Should have using OpenAPI
+    expect(tsp).toContain("using OpenAPI;");
+    // Should have both decorators
+    expect(tsp).toContain('@extension("x-ms-list-prev-link", true)');
+    expect(tsp).toContain("@prevLink");
+  });
+});