Skip to content
Vouch Docs

Refresh the API reference

The Reference → API Reference pages are generated from the FastAPI app, not hand-written. After you change a route or a Pydantic schema, regenerate the committed spec so the published docs match the code.

Regenerate

Section titled “Regenerate”
Terminal window
cd docs-site
npm run sync:api

This runs scripts/refresh-openapi.sh, which calls server/scripts/dump_openapi.py (via uv) and overwrites docs-site/src/openapi.json. Commit the updated JSON alongside your API change.

Make the reference read well

Section titled “Make the reference read well”

The reference is only as good as the annotations in the code. To improve a page, change the server, then regenerate:

  • Add summary= and description= to your FastAPI route decorators.
  • Group endpoints with tags=.
  • Give Pydantic fields descriptions and examples.
@router.post(
    "/me/contact-set",
    summary="Publish an encrypted contact set",
    description="Uploads P·k for each contact plus the encrypted own-token.",
    tags=["profile"],
)
async def publish_contact_set(...): ...

Then npm run sync:api and the reference reflects it.

Don’t hand-edit the JSON

Section titled “Don’t hand-edit the JSON”

src/openapi.json is a build artefact. It’s committed only so the site builds without a Python toolchain present; CI regenerates it before every publish, so any manual edit is overwritten. The source of truth is always the code.