Document cache
The document cache is the last document a URL source downloaded. Only URL sources have one: a file is its own document, and a server project writes its document on every build.
Where it lives
Section titled “Where it lives”By default the cache is the client’s copy of the document in obj, obj/<configuration>/<framework>/openapi/<ClientName>/openapi.json.
It survives builds, but not dotnet clean or a clean clone.
DocumentCache names a file in the project instead, relative to the project. That file can be committed, so every clone and every CI
agent starts with a cache.
What a build does
Section titled “What a build does”For each URL client, a build:
- Decides whether to download. It downloads unless updating is off (below) and the cache exists.
- Downloads the document into the client’s
download/folder, retrying twice. - If the download succeeded and differs from the cache, updates the cache: overwrites it with the download.
- If the download failed, uses the cache, with warning
CHIRO104. With no cache, the build fails withCHIRO105. - Generates the client from the cache, through the same copy-when-changed step as every source.
So a download that returns what the cache already holds changes no file and regenerates nothing.
Updating
Section titled “Updating”Updating is on by default: every build that reaches the URL takes the API’s latest document. That suits a cache in obj, or a
committed cache whose diffs you review.
Turn it off to decide when a change reaches the client. With updating off and a cache present, the build doesn’t download at all:
- for every client, with the property
ChirographUpdateOpenApiDocumentCacheset tofalse; - for one client, with the metadata
UpdateDocumentCache="false", which wins over the property.
To take the changes later, build once with -p:ChirographUpdateOpenApiDocumentCache=true (which works for clients that don’t set the
metadata), or delete the cache file. A client with updating off and no cache still downloads once, to fill it.
From a URL walks through committing the cache and building in CI without network.