feat(openapi3): add @pageSize decorator support for x-ms-list-page-size extension (#9618)

OpenAPI parameters with `x-ms-list-page-size: true` were not being
converted to TypeSpec's `@pageSize` decorator during import.

## Changes

- **Modified `getParameterDecorators()`** in `decorators.ts` to detect
`x-ms-list-page-size` extension and emit `@pageSize` decorator when
`true`
- **Added tests** covering true/false/absent cases and full document
rendering

## Example

OpenAPI parameter:
```yaml
parameters:
  - name: page_size
    in: query
    schema:
      type: integer
      format: int32
    x-ms-list-page-size: true
```

Now converts to:
```typescript
@extension("x-ms-list-page-size", true)
@pageSize
@query
page_size: int32
```

Note: The `@extension` decorator was already being emitted; this adds
the semantic `@pageSize` decorator alongside it.

<!-- 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 pageSize 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:
        - name: page_size
          in: query
          required: true
          schema:
            type: integer
            format: int32
          #this is the extension that matters
          x-ms-list-page-size: true
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Widget'
        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:
 ...

</details>



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

- Fixes #9616

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

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

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-openapi-page-size-support-2026-1-6-17-39-30.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+importer - Add support for `@pageSize` decorator based on x-ms-list-page-size extension

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

@@ -91,6 +91,15 @@ export function getParameterDecorators(parameter: OpenAPI3Parameter | OpenAPIPar
     decorators.push(...getDecoratorsForSchema(parameter.schema));
   }
 
+  // Add @pageSize decorator if x-ms-list-page-size extension is true
+  const xmsListPageSize = (parameter as any)["x-ms-list-page-size"];
+  if (xmsListPageSize === true) {
+    decorators.push({
+      name: "pageSize",
+      args: [],
+    });
+  }
+
   // Handle x-ms-list-continuation-token extension on parameter itself
   const xmsListContinuationToken = (parameter as any)["x-ms-list-continuation-token"];
   if (xmsListContinuationToken === true) {

packages/openapi3/test/tsp-openapi3/parameters.test.ts

@@ -728,3 +728,153 @@ describe("query", () => {
     });
   });
 });
+
+describe("x-ms-list-page-size extension", () => {
+  it("adds @pageSize decorator when x-ms-list-page-size is true", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      parameters: {
+        PageSize: {
+          name: "page_size",
+          in: "query",
+          required: true,
+          schema: {
+            type: "integer",
+            format: "int32",
+          },
+          "x-ms-list-page-size": true,
+        } as any,
+      },
+    });
+
+    const parametersNamespace = serviceNamespace.namespaces.get("Parameters");
+    assert(parametersNamespace, "Parameters namespace not found");
+
+    const models = parametersNamespace.models;
+    const PageSize = models.get("PageSize");
+    assert(PageSize, "PageSize model not found");
+    expect(PageSize.properties.size).toBe(1);
+
+    const pageSizeProperty = PageSize.properties.get("page_size");
+    assert(pageSizeProperty, "page_size property not found");
+
+    // Should have @query, @extension, and @pageSize decorators
+    expectDecorators(
+      pageSizeProperty.decorators,
+      [
+        { name: "extension", args: ["x-ms-list-page-size", true] },
+        { name: "pageSize" },
+        { name: "query" },
+      ],
+      { strict: false },
+    );
+  });
+
+  it("renders complete TypeSpec with @pageSize decorator", async () => {
+    const tsp = await renderTypeSpecForOpenAPI3({
+      paths: {
+        "/widgets": {
+          get: {
+            operationId: "listWidgets",
+            description: "List widgets",
+            parameters: [
+              {
+                name: "page_size",
+                in: "query",
+                required: true,
+                schema: {
+                  type: "integer",
+                  format: "int32",
+                },
+                "x-ms-list-page-size": true,
+                explode: false,
+              } as any,
+            ],
+            responses: {
+              "200": {
+                description: "The request has succeeded.",
+                content: {
+                  "application/json": {
+                    schema: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: {
+                          id: { type: "string" },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    // Should include @pageSize and @extension decorators
+    expect(tsp).toContain("@pageSize");
+    expect(tsp).toContain('@extension("x-ms-list-page-size", true)');
+  });
+
+  it("does not add @pageSize decorator when x-ms-list-page-size is false", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      parameters: {
+        PageSize: {
+          name: "page_size",
+          in: "query",
+          required: true,
+          schema: {
+            type: "integer",
+            format: "int32",
+          },
+          "x-ms-list-page-size": false,
+        } as any,
+      },
+    });
+
+    const parametersNamespace = serviceNamespace.namespaces.get("Parameters");
+    assert(parametersNamespace, "Parameters namespace not found");
+
+    const models = parametersNamespace.models;
+    const PageSize = models.get("PageSize");
+    assert(PageSize, "PageSize model not found");
+
+    const pageSizeProperty = PageSize.properties.get("page_size");
+    assert(pageSizeProperty, "page_size property not found");
+
+    // Should only have @query and @extension decorators, not @pageSize
+    const hasPageSize = pageSizeProperty.decorators.some((d) => d.definition?.name === "@pageSize");
+    expect(hasPageSize).toBe(false);
+  });
+
+  it("does not add @pageSize decorator when x-ms-list-page-size is absent", async () => {
+    const serviceNamespace = await tspForOpenAPI3({
+      parameters: {
+        PageSize: {
+          name: "page_size",
+          in: "query",
+          required: true,
+          schema: {
+            type: "integer",
+            format: "int32",
+          },
+        },
+      },
+    });
+
+    const parametersNamespace = serviceNamespace.namespaces.get("Parameters");
+    assert(parametersNamespace, "Parameters namespace not found");
+
+    const models = parametersNamespace.models;
+    const PageSize = models.get("PageSize");
+    assert(PageSize, "PageSize model not found");
+
+    const pageSizeProperty = PageSize.properties.get("page_size");
+    assert(pageSizeProperty, "page_size property not found");
+
+    // Should only have @query decorator, not @pageSize
+    const hasPageSize = pageSizeProperty.decorators.some((d) => d.definition?.name === "@pageSize");
+    expect(hasPageSize).toBe(false);
+  });
+});