Skip to content

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.

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.

For each URL client, a build:

  1. Decides whether to download. It downloads unless updating is off (below) and the cache exists.
  2. Downloads the document into the client’s download/ folder, retrying twice.
  3. If the download succeeded and differs from the cache, updates the cache: overwrites it with the download.
  4. If the download failed, uses the cache, with warning CHIRO104. With no cache, the build fails with CHIRO105.
  5. 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 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 ChirographUpdateOpenApiDocumentCache set to false;
  • 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.