{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"client","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]}," configuration contains the settings for the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/generate-client"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate-client"]}]}," command."," ","You can put the block at the root of the configuration file, where it holds the defaults."," ","You can also put it inside an ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/configuration/reference/apis"},"children":["API-specific section"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis.<name>.client"]},"), where it overrides the root block for that API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The input and output are not part of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]}," block:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["input"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis.<name>.root"]},", or a path or alias that you give on the command line."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["output"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis.<name>.clientOutput"]},"."," ","If you omit it, the default is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<name>.client.ts"]}," next to the configuration file."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--output"]}," flag overrides it when you generate one API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":2},"children":["Options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each scalar option matches the related CLI flag and has the same default."," ","See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/generate-client#options"},"children":["command options"]}," for the full description of each value."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination"]}," option is available only in the configuration file."," ","It is a structured, durable contract that belongs in versioned configuration, not in a shell string."," ","If you run without a configuration file, declare pagination for each operation with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-redoclyPagination"]}," extension in the description."," ","As an alternative, pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination"]}," to the programmatic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generateClient(...)"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generators"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The generators to run, in order. Each entry is a built-in name (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["typescript"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zod"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tanstack-query"]}," or its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-vue"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-svelte"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-solid"]}," variants, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["swr"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mock"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transformers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cli"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["python"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["go"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["php"]},"), or the path or package name of a custom generator."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outputMode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The file layout: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["single"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]},". This option applies to TypeScript output only. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["python"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["go"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["php"]}," SDKs always emit one client module (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["module"]}," runtime adds their runtime files beside it)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runtime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The runtime distribution: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inline"]}," (the runtime is embedded in the generated output) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["module"]}," (the runtime is written as real files in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runtime/"]}," folder beside the client)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["importExt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The extension in generated relative imports: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["js"]}," (default, for tsc and bundlers) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ts"]}," (for Node's built-in type stripping). This option applies to TypeScript output only."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["argsStyle"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How the client receives operation inputs: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grouped"]}," (default) groups them by transport layer (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["query"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cookies"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]},"), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flat"]}," merges them into one object. This option applies to TypeScript output only. Each language SDK follows its own idiom (keyword arguments, named arguments, a params struct)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How operations report HTTP errors: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["throw"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["python"]}," SDK implements both. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["go"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["php"]}," SDKs support only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["throw"]},", because that is the language idiom, and they reject ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dateType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The type of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date-time"]}," fields: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Date"]},". Every language applies it: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Date"]}," in TypeScript, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["datetime"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]}," in Python, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time.Time"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Date"]}," in Go, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DateTimeImmutable"]}," in PHP."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mockData"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The data mode for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mock"]}," generator: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["faker"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mockSeed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The seed for mocks in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["faker"]}," mode."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queryKeyPrefix"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The first element of every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tanstack-query"]}," query key and mutation key. It separates the cache entries when several generated APIs share one QueryClient. This option is available only in the configuration file and has no flag."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codeSamples"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<output>.code-samples.yaml"]}," next to the client. This file is an OpenAPI Overlay that adds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-codeSamples"]}," to each operation. The samples come from each selected generator that implements ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sample()"]},". To add the samples to your API description, apply the file with the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/bundle#apply-overlays"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}]}," command. This option is available only in the configuration file and has no flag."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serverUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The server URL that the client includes as its default. If you do not set it, the client uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["servers[0].url"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["goPackage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The package clause for the output of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["go"]}," generator. The value must be a valid Go package name: lowercase letters, digits, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]},", with no digit at the start, and not a keyword. An invalid value stops generation, so the generator does not emit a file that Go cannot compile. Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cliOutput"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The path of a composed CLI entry. The entry includes every api that emits a cli module: from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cli"]}," generator by name, ejected, or included as a prerequisite. The result is one binary. You address each api by its alias, and each api has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<BINNAME>_<ALIAS>_*"]}," credential variables. This option is available only in the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]}," block. See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/use-generated-client#compose-and-extend-the-cli"},"children":["Compose and extend the CLI"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Options for each generator, keyed by generator name. The command validates each entry against the schema that the generator declares. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["python"]}," generator accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["models"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataclass"]}," (default) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pydantic"]},". See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/customize-client-generation#custom-generators"},"children":["Custom generators"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Also write the reference documentation for what the run generates: one Markdown page for each selected generator that documents itself (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<output>.cli.md"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<output>.python.md"]},", and so on). The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--docs"]}," flag sets it too. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docsFrontmatter"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Emit YAML front matter carrying the title above each documentation page, for docs sites that expect it. This option is available only in the configuration file. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The path to a publisher setup module that the client includes. The module sets defaults such as the server URL, retries, headers, and middleware. See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/customize-client-generation#publisher-defaults"},"children":["Publisher defaults"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#pagination-object"},"children":["Pagination object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Declares how the API paginates. Paginated operations then get typed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".pages()"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".items()"]}," async iterators."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pagination-object","__idx":3},"children":["Pagination object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination"]}," block is an optional convention rule, plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operations"]}," overrides for single operations and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude"]}," list."," ","The convention rule uses the rule fields below."," ","When you set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["style"]},", the rule applies to each operation that it structurally fits."," ","See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/use-generated-client#pagination"},"children":["Pagination in the usage guide"]}," to learn how the generated iterators behave."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["style"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How the iterator advances: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}," (follow a response cursor), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," (advance an offset by the item count of each page), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," (increment a page number), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," (follow the RFC 8288 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link"]}," header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rel=\"next\""]}," in the response). The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," style has no advance parameter. As a convention rule, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," fits only the operations whose response documents a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link"]}," header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursorParam"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The query parameter that receives the cursor. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]}," for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}," style."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextCursor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The JSON pointer (RFC 6901, starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]},") to the next cursor in the response. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]}," for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}," style."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasMore"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}," style): the JSON pointer to a boolean \"more pages\" flag. Iteration stops when the flag resolves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},". Use it for APIs whose cursor stays non-null on the last page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offsetParam"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The query parameter that the iterator advances. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]}," for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," styles."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limitParam"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional: the page-size query parameter for any style. The generator records it for tooling. The iterator never sets it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The JSON pointer to the item array of the page in the response. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["''"]}," if the response body is the item array itself."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The operationIds that no source may paginate. This list wins over overrides, extensions, and the convention."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["map of operationId → rule"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rules for single operations, with the same fields as the convention. Each entry overrides the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-redoclyPagination"]}," extension in the description and the convention."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The generator verifies the rules at generate time."," ","The advance parameter must be a declared query parameter of the correct type: string for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]},", numeric for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},"."," ","The JSON pointers must resolve in the JSON success-response schema of the operation."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}," pointer must point to an array, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasMore"]}," pointer must point to a boolean."," ","If the convention does not fit an operation, the generator skips that operation."," ","If an explicit rule does not fit, generation fails."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-redoclyPagination"]}," operation extension in the API description uses the same rule fields."," ","For each operation, the precedence is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operations[id]"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-redoclyPagination"]},", then the convention."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-defaults-with-a-per-api-override","__idx":5},"children":["Configure defaults with a per-API override"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An API with its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]}," block uses that block instead of the top-level block."," ","The top-level block applies to APIs without their own block."," ","A file-path invocation that matches no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis:"]}," entry uses the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]},"."," ","CLI flags override the resolved configuration."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"client:\n  generators:\n    - typescript\n  argsStyle: grouped\napis:\n  cafe:\n    root: ./openapi.yaml\n    clientOutput: ./src/api/client.ts\n    client: # replaces the top-level block for this API\n      generators:\n        - typescript\n        - zod\n      argsStyle: flat\n  orders:\n    root: ./orders.yaml # no client block — uses the top-level one\n    clientOutput: ./src/api/orders.client.ts\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"declare-pagination","__idx":6},"children":["Declare pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Declare the convention one time, with overrides and exclusions for single operations:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"client:\n  pagination:\n    style: cursor\n    cursorParam: cursor\n    nextCursor: /nextCursor\n    items: /orders\n    exclude:\n      - listOrderEvents\n    operations:\n      listMenuItems:\n        style: page\n        offsetParam: page\n        items: /data\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For code-level control, use the programmatic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generateClient(...)"]}," API instead."," ","With this API, you can also register ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/customize-client-generation#custom-generators"},"children":["custom generators"]}," inline."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-options","__idx":7},"children":["Related options"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/configuration/reference/apis"},"children":["apis"]}," settings define the root document, the output, and the overrides for each API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":8},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/generate-client"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate-client"]}," command"]}]}," - Learn about the the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate-client"]}," command's flags, output modes, and invocation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/use-generated-client"},"children":["Use the generated client"]}]}," - Learn how to use the client produced by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate-client"]}," command"]}]}]},"frontmatter":{},"tagList":[],"title":"client","lastModified":"2026-09-29T07:29:49.000Z"}