@typespec/http-specs 0.1.0-alpha.9 → 0.1.0-dev.1

package/specs/payload/pageable/main.tsp

@@ -1,8 +1,10 @@
 import "@typespec/http";
 import "@typespec/spector";
+import "@typespec/xml";
 
 using Http;
 using Spector;
+using Xml;
 
 /**
  * Test for pageable payload.
@@ -15,6 +17,11 @@ model Pet {
   name: string;
 }
 
+alias HeaderAndQuery = {
+  @header foo?: string;
+  @query bar?: string;
+};
+
 @route("/server-driven-pagination")
 namespace ServerDrivenPagination {
   @scenario
@@ -52,4 +59,645 @@ namespace ServerDrivenPagination {
 
     @nextLink next?: url;
   };
+
+  @scenario
+  @scenarioDoc("""
+    Test case for using link as pagination with string nextLink.
+    
+    Two requests need to be tested.
+    1. Initial request:
+    Expected route: /payload/pageable/server-driven-pagination/link-string
+    Expected response body:
+    ```json
+    { "pets": [
+        { "id": "1", "name": "dog" },
+        { "id": "2", "name": "cat" }
+      ],
+      "next": "http://[host]:[port]/payload/pageable/server-driven-pagination/link-string/nextPage"
+    }
+    ```
+    2. Next page request:
+    Expected route: /payload/pageable/server-driven-pagination/link-string/nextPage
+    Expected response body:
+    ```json
+    { "pets": [
+        { "id": "3", "name": "bird" },
+        { "id": "4", "name": "fish" }
+      ]
+    }
+    ```
+    """)
+  @route("/link-string")
+  @list
+  op linkString(): {
+    @pageItems
+    pets: Pet[];
+
+    @nextLink next?: string;
+  };
+
+  @scenario
+  @scenarioDoc("""
+    Test case for using link as pagination with nested structure.
+    
+    Two requests need to be tested.
+    1. Initial request:
+    Expected route: /payload/pageable/server-driven-pagination/nested-link
+    Expected response body:
+    ```json
+    { "nestedItems": {
+        "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ]
+      },
+      "nestedNext": {
+        "next": "http://[host]:[port]/payload/pageable/server-driven-pagination/nested-link/nextPage"
+      }
+    }
+    ```
+    2. Next page request:
+    Expected route: /payload/pageable/server-driven-pagination/nested-link/nextPage
+    Expected response body:
+    ```json
+    { "nestedItems": {
+        "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+        ]
+      }
+    }
+    ```
+    """)
+  @route("/nested-link")
+  @list
+  op nestedLink(): {
+    nestedItems: {
+      @pageItems
+      pets: Pet[];
+    };
+    nestedNext: {
+      @nextLink next?: url;
+    };
+  };
+
+  /** Scenario where the initial request is not a GET request. However following the next link always result in a GET request. */
+  namespace AlternateInitialVerb {
+    model Filter {
+      filter: string;
+    }
+
+    @scenario
+    @scenarioDoc("""
+      Test case for initial POST request followed by GET for next pages using link pagination.
+      The initial request is a POST with a filter body, and the next page is fetched using a GET request on the next link.
+      
+      Two requests need to be tested.
+      1. Initial request (POST):
+      Expected route: /payload/pageable/server-driven-pagination/link/initial-post
+      Expected request body:
+      ```json
+      { "filter": "foo eq bar" }
+      ```
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ],
+        "next": "http://[host]:[port]/payload/pageable/server-driven-pagination/link/initial-post/nextPage?token=abc"
+      }
+      ```
+      2. Next page request (GET):
+      Expected route: /payload/pageable/server-driven-pagination/link/initial-post/nextPage?token=abc
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+        ]
+      }
+      ```
+      """)
+    @route("/link/initial-post")
+    @list
+    @post
+    op post(@body body: Filter): {
+      @pageItems pets: Pet[];
+      @nextLink next?: url;
+    };
+  }
+
+  @route("/continuationtoken")
+  namespace ContinuationToken {
+    @scenario
+    @scenarioDoc("""
+      Test case for using continuation token as pagination. Continuation token is passed in the request query and response body.
+      
+      Two requests need to be tested.
+      
+      1. Initial request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-query-response-body?bar=bar
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ],
+        "nextToken": "page2"
+      }
+      ```
+      
+      2. Next page request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-query-response-body?bar=bar&token=page2
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+        ]
+      }
+      ```
+      """)
+    @route("/request-query-response-body")
+    @list
+    op requestQueryResponseBody(@continuationToken @query token?: string, ...HeaderAndQuery): {
+      @pageItems
+      pets: Pet[];
+
+      @continuationToken nextToken?: string;
+    };
+
+    @scenario
+    @scenarioDoc("""
+      Test case for using continuation token as pagination. Continuation token is passed in the request header and response body.
+      
+      Two requests need to be tested.
+      
+      1. Initial request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-header-response-body?bar=bar      
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ],
+        "nextToken": "page2"
+      }
+      ```
+      
+      2. Next page request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-header-response-body?bar=bar
+      
+      Expected request header:
+      token=page2
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+        ]
+      }
+      ```
+      """)
+    @route("/request-header-response-body")
+    @list
+    op requestHeaderResponseBody(@continuationToken @header token?: string, ...HeaderAndQuery): {
+      @pageItems
+      pets: Pet[];
+
+      @continuationToken nextToken?: string;
+    };
+
+    @scenario
+    @scenarioDoc("""
+      Test case for using continuation token as pagination. Continuation token is passed in the request query and response header.
+      
+      Two requests need to be tested.
+      
+      1. Initial request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-query-response-header?bar=bar
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ]
+      }
+      ```
+      
+      Expected response header:
+      next-token=page2
+      
+      2. Next page request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-query-response-header?bar=bar&token=page2
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+        ]
+      }
+      ```
+      """)
+    @route("/request-query-response-header")
+    @list
+    op requestQueryResponseHeader(@continuationToken @query token?: string, ...HeaderAndQuery): {
+      @pageItems
+      pets: Pet[];
+
+      @continuationToken @header nextToken?: string;
+    };
+
+    @scenario
+    @scenarioDoc("""
+      Test case for using continuation token as pagination. Continuation token is passed in the request header and response header.
+      
+      Two requests need to be tested.
+      1. Initial request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-header-response-header?bar=bar
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ]
+      }
+      ```
+      
+      Expected response header:
+      next-token=page2
+      
+      2. Next page request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-header-response-header?bar=bar
+      
+      Expected request header:
+      token=page2
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+        ]
+      }
+      ```
+      """)
+    @route("/request-header-response-header")
+    @list
+    op requestHeaderResponseHeader(@continuationToken @header token?: string, ...HeaderAndQuery): {
+      @pageItems
+      pets: Pet[];
+
+      @continuationToken @header nextToken?: string;
+    };
+
+    @scenario
+    @scenarioDoc("""
+      Test case for using continuation token as pagination with nested response structure. Continuation token is passed in the request query and nested within response body.
+      
+      Two requests need to be tested.
+      
+      1. Initial request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-query-nested-response-body?bar=bar
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "nestedItems": {
+          "pets": [
+          { "id": "1", "name": "dog" },
+          { "id": "2", "name": "cat" }
+        ]
+        },
+        "nestedNext": {
+          "nextToken": "page2"
+        }
+      }
+      ```
+      
+      2. Next page request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-query-nested-response-body?bar=bar&token=page2
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "nestedItems": {
+          "pets": [
+          { "id": "3", "name": "bird" },
+          { "id": "4", "name": "fish" }
+          ]
+        }
+      }
+      ```
+      """)
+    @route("/request-query-nested-response-body")
+    @list
+    op requestQueryNestedResponseBody(
+      @continuationToken @query token?: string,
+      ...HeaderAndQuery,
+    ): {
+      nestedItems: {
+        @pageItems
+        pets: Pet[];
+      };
+      nestedNext?: {
+        @continuationToken nextToken?: string;
+      };
+    };
+
+    @scenario
+    @scenarioDoc("""
+      Test case for using continuation token as pagination with nested response structure. Continuation token is passed in the request header and nested within response body.
+      
+      Two requests need to be tested.
+      
+      1. Initial request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-header-nested-response-body?bar=bar
+      
+      Expected request header:
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "nestedItems": {
+          "pets": [
+            { "id": "1", "name": "dog" },
+            { "id": "2", "name": "cat" }
+          ]
+        },
+        "next": {
+          "nextToken": "page2"
+        }
+      }
+      ```
+      
+      2. Next page request:
+      Expected route: /payload/pageable/server-driven-pagination/continuationtoken/request-header-nested-response-body?bar=bar
+      
+      Expected request header:
+      token=page2
+      foo=foo
+      
+      Expected response body:
+      ```json
+      { "nestedItems": {
+          "pets": [
+            { "id": "3", "name": "bird" },
+            { "id": "4", "name": "fish" }
+          ]
+        }
+      }
+      ```
+      """)
+    @route("/request-header-nested-response-body")
+    @list
+    op requestHeaderNestedResponseBody(
+      @continuationToken @header token?: string,
+      ...HeaderAndQuery,
+    ): {
+      nestedItems: {
+        @pageItems
+        pets: Pet[];
+      };
+      nestedNext?: {
+        @continuationToken nextToken?: string;
+      };
+    };
+  }
+}
+
+@route("/pagesize")
+namespace PageSize {
+  @scenario
+  @scenarioDoc("""
+    Test case for simple pagination without nextlink or continuationToken.
+    
+    Single request:
+    Expected route: /payload/pageable/pagesize/without-continuation
+    
+    Expected response body:
+    ```json
+    { "pets": [
+        { "id": "1", "name": "dog" },
+        { "id": "2", "name": "cat" },
+        { "id": "3", "name": "bird" },
+        { "id": "4", "name": "fish" }
+      ]
+    }
+    ```
+    """)
+  @route("/without-continuation")
+  @list
+  op listWithoutContinuation(): {
+    @pageItems
+    pets: Pet[];
+  };
+
+  @scenario
+  @scenarioDoc("""
+    Test case for pagination with a regular @pageSize parameter.
+    
+    Two requests need to be tested:
+    1. Request with pageSize=2:
+    Expected route: /payload/pageable/pagesize/list?pageSize=2
+    
+    Expected response body:
+    ```json
+    { "pets": [
+        { "id": "1", "name": "dog" },
+        { "id": "2", "name": "cat" }
+      ]
+    }
+    ```
+    
+    2. Request with pageSize=4:
+    Expected route: /payload/pageable/pagesize/list?pageSize=4
+    
+    Expected response body:
+    ```json
+    { "pets": [
+        { "id": "1", "name": "dog" },
+        { "id": "2", "name": "cat" },
+        { "id": "3", "name": "bird" },
+        { "id": "4", "name": "fish" }
+      ]
+    }
+    ```
+    """)
+  @route("/list")
+  @list
+  op listWithPageSize(@pageSize @query pageSize?: int32): {
+    @pageItems
+    pets: Pet[];
+  };
+}
+
+@doc("An XML pet item.")
+@name("Pet")
+model XmlPet {
+  @name("Id") id: string;
+  @name("Name") name: string;
+}
+
+@route("/xml")
+namespace XmlPagination {
+  @scenario
+  @scenarioDoc("""
+    Test case for XML pagination with continuation token. Continuation token is passed in the request query and response body.
+    
+    Two requests need to be tested.
+    
+    1. Initial request:
+    Expected route: /payload/pageable/xml/list
+    
+    Expected response body:
+    ```xml
+    <PetListResult>
+      <Pets>
+        <Pet>
+          <Id>1</Id>
+          <Name>dog</Name>
+        </Pet>
+        <Pet>
+          <Id>2</Id>
+          <Name>cat</Name>
+        </Pet>
+      </Pets>
+      <NextMarker>page2</NextMarker>
+    </PetListResult>
+    ```
+    
+    2. Next page request:
+    Expected route: /payload/pageable/xml/list?marker=page2
+    
+    Expected response body:
+    ```xml
+    <PetListResult>
+      <Pets>
+        <Pet>
+          <Id>3</Id>
+          <Name>bird</Name>
+        </Pet>
+        <Pet>
+          <Id>4</Id>
+          <Name>fish</Name>
+        </Pet>
+      </Pets>
+    </PetListResult>
+    ```
+    """)
+  @route("/list-with-continuation")
+  @list
+  op listWithContinuation(@continuationToken @query marker?: string): {
+    @header("content-type") contentType: "application/xml";
+    @body body: XmlPetListResult;
+  };
+
+  @scenario
+  @scenarioDoc("""
+    Test case for XML pagination with next link.
+    
+    Two requests need to be tested.
+    
+    1. Initial request:
+    Expected route: /payload/pageable/xml/list-with-next-link
+    
+    Expected response body:
+    ```xml
+    <PetListResult>
+      <Pets>
+        <Pet>
+          <Id>1</Id>
+          <Name>dog</Name>
+        </Pet>
+        <Pet>
+          <Id>2</Id>
+          <Name>cat</Name>
+        </Pet>
+      </Pets>
+      <NextLink>http://[host]:[port]/payload/pageable/xml/list-with-next-link/nextPage</NextLink>
+    </PetListResult>
+    ```
+    
+    2. Next page request:
+    Expected route: /payload/pageable/xml/list-with-next-link/nextPage
+    
+    Expected response body:
+    ```xml
+    <PetListResult>
+      <Pets>
+        <Pet>
+          <Id>3</Id>
+          <Name>bird</Name>
+        </Pet>
+        <Pet>
+          <Id>4</Id>
+          <Name>fish</Name>
+        </Pet>
+      </Pets>
+    </PetListResult>
+    ```
+    """)
+  @route("/list-with-next-link")
+  @list
+  op listWithNextLink(): {
+    @header("content-type") contentType: "application/xml";
+    @body body: XmlPetListResultWithNextLink;
+  };
+}
+
+@doc("The XML response for listing pets.")
+@name("PetListResult")
+model XmlPetListResult {
+  @pageItems
+  @name("Pets")
+  pets: XmlPet[];
+
+  @continuationToken
+  @name("NextMarker")
+  nextMarker?: string;
+}
+
+@doc("The XML response for listing pets with next link.")
+@name("PetListResult")
+model XmlPetListResultWithNextLink {
+  @pageItems
+  @name("Pets")
+  pets: XmlPet[];
+
+  @nextLink
+  @name("NextLink")
+  nextLink?: url;
 }