[doc] client code of paging operation (#2269)

resolve: #2138

---------

Co-authored-by: Weidong Xu <[email protected]>
Co-authored-by: Mark Cowlishaw <[email protected]>
Co-authored-by: Yuchao Yan <[email protected]>

Author: 4 people

.chronus/changes/add_page_items_segments-2025-2-4-15-27-53.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Add `pageItemsSegments` for `SdkPagingServiceMetadata` to indicate how to get page items from response.
+Add `pageItemsSegments` for `SdkPagingServiceMetadata` to indicate how to get page items from response.

.chronus/changes/decorator-override-2025-2-14-15-58-44.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Specific scope decorator should always override all-scopes decorator
+Specific scope decorator should always override all-scopes decorator.

.chronus/changes/tcgc-addAccessForModelProperty-2025-2-12-16-35-32.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Extend `@access` to also apply to `ModelProperty`s
+Extend `@access` to also apply to `ModelProperty`s.

.chronus/changes/tcgc-addNamespaceFlag-2025-2-6-16-20-54.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Add `namespace` flag to tcgc
+Add `namespace` flag to tcgc.

.chronus/changes/tcgc-migrateToMutator-2025-2-4-12-45-51.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Move from projections to mutators
+Move from projections to mutators.

.chronus/changes/typespec_azure_rulsets-2024-6-19-19-0-31.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-add linter rulesets to TCGC, for both generic and language-specific linter rules
+Add linter rulesets to TCGC, for both generic and language-specific linter rules.

website/src/content/docs/docs/howtos/Generate client libraries/13pagingOperations.mdx

@@ -0,0 +1,289 @@
+---
+title: Paging Operations
+---
+
+import { ClientTabs, ClientTabItem } from "@components/client-tabs";
+
+This doc details what emitters will generate for paging operations.
+
+## Using next link to indicate how to get the next page
+
+Next link is an absolute url returned by the paging operation, which indicates how to get the next page.
+If the response does not return a next link, it indicates the last page of results.
+Next link should be annotated in the response model with `@nextLink`.
+
+There are two ways to indicate a paging operation with `@nextLink`:
+
+1. Use `@pagedResult` and `@items` in `Azure.Core` lib.
+
+<ClientTabs>
+
+```typespec
+op listWithPage(): UserList;
+
+model User {
+  id: string;
+  name: string;
+}
+
+@pagedResult
+model UserList {
+  @items
+  value: User[];
+
+  @nextLink
+  nextLink?: url;
+}
+```
+
+```python
+class User(_model_base.Model):
+    id: str = rest_field()
+    name: str = rest_field()
+
+def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
+    ...
+```
+
+```csharp
+// TODO
+```
+
+```typescript
+// TODO
+```
+
+```java
+public PagedIterable<User> listWithPage();
+```
+
+</ClientTabs>
+
+2. Use the `@list` and `@pageItems` decorators from TypeSpec core.
+
+<ClientTabs>
+
+```typespec
+@list
+op listWithPage(): UserList;
+
+model User {
+  id: string;
+  name: string;
+}
+
+model UserList {
+  @pageItems
+  value: User[];
+
+  @nextLink
+  nextLink?: url;
+}
+```
+
+```python
+class User(_model_base.Model):
+    id: str = rest_field()
+    name: str = rest_field()
+
+def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
+    ...
+```
+
+```csharp
+// TODO
+```
+
+```typescript
+// TODO
+```
+
+```java
+public PagedIterable<User> listWithPage();
+```
+
+</ClientTabs>
+
+## Using continuation token to indicate how to get the next page
+
+A continuation token is a string returned by a paging operation, which is used as a parameter value for the paging operation to get the next page.
+If the response does not return a continuation token, it indicates the last page of results.
+The request parameter that corresponds to the continuation token value in the paging operation should be decorated with `@continuationToken`. Similarly, the response property that contains the continuation token value should also be decorated with `@continuationToken`.
+
+1. Continuation token in query parameter and response body.
+
+<ClientTabs>
+
+```typespec
+@list
+op listWithPage(@query @continuationToken continuationToken?: string): UserList;
+
+model User {
+  id: string;
+  name: string;
+}
+
+model UserList {
+  @pageItems
+  value: User[];
+
+  @continuationToken
+  continuationToken?: string;
+}
+```
+
+```python
+class User(_model_base.Model):
+    id: str = rest_field()
+    name: str = rest_field()
+
+def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
+    ...
+```
+
+```csharp
+// TODO
+```
+
+```typescript
+// TODO
+```
+
+```java
+NOT_SUPPORTED
+```
+
+</ClientTabs>
+
+2. Continuation token in header parameter and response body.
+
+<ClientTabs>
+
+```typespec
+@list
+op listWithPage(@header @continuationToken continuationToken?: string): UserList;
+
+model User {
+  id: string;
+  name: string;
+}
+
+model UserList {
+  @pageItems
+  value: User[];
+
+  @continuationToken
+  continuationToken?: string;
+}
+```
+
+```python
+class User(_model_base.Model):
+    id: str = rest_field()
+    name: str = rest_field()
+
+def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
+    ...
+```
+
+```csharp
+// TODO
+```
+
+```typescript
+// TODO
+```
+
+```java
+NOT_SUPPORTED
+```
+
+</ClientTabs>
+
+3. Continuation token in query parameter and response header.
+
+<ClientTabs>
+
+```typespec
+@list
+op listWithPage(@query @continuationToken continuationToken?: string): {
+  @header
+  @continuationToken
+  continuationToken?: string;
+
+  @pageItems
+  value: User[];
+};
+
+model User {
+  id: string;
+  name: string;
+}
+```
+
+```python
+class User(_model_base.Model):
+    id: str = rest_field()
+    name: str = rest_field()
+
+def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
+    ...
+```
+
+```csharp
+// TODO
+```
+
+```typescript
+// TODO
+```
+
+```java
+NOT_SUPPORTED
+```
+
+</ClientTabs>
+
+4. Continuation token in header parameter and response header.
+
+<ClientTabs>
+
+```typespec
+@list
+op listWithPage(@query @continuationToken continuationToken?: string): {
+  @header
+  @continuationToken
+  continuationToken?: string;
+
+  @pageItems
+  value: User[];
+};
+
+model User {
+  id: string;
+  name: string;
+}
+```
+
+```python
+class User(_model_base.Model):
+    id: str = rest_field()
+    name: str = rest_field()
+
+def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
+    ...
+```
+
+```csharp
+// TODO
+```
+
+```typescript
+// TODO
+```
+
+```java
+NOT_SUPPORTED
+```
+
+</ClientTabs>