Skip to content

Testing and Documentation Guide

This guide covers how to write documentation for CoreAPI's domains, and how to use that documentation to test your API changes.

Cloning the documentation repo

CoreAPI's docs live in a separate repo, kept independent from CoreAPI itself so documentation can be built/deployed on its own:

git clone https://mashup.castis.io/playtelly/documentations.git

Each domain has its own folder under docs/domain/<domain>/, containing an index.md, a changelog.md, and an OpenAPI spec (<domain>.yaml) — e.g. docs/domain/commerce/commerce.yaml.

Updating documentation alongside code changes

Whenever you make changes to a domain's API calls, please also update:

  • changelog.md — add a dated entry describing what changed and why, following the existing format in that domain's changelog. See docs/domain/media/changelog.md for the level of detail expected — what changed, why, and any client-side impact (e.g. new response shape, a field that moved, a route that was removed).
  • The domain's <domain>.yaml — this is the OpenAPI spec that gets imported into the docs site and powers the interactive "try it" panel. Add or update the relevant paths:, request/response schemas, and examples for any endpoint you touched or added.

Running the docs locally

make apidocs-d

Then open http://localhost:8001.

Testing your API via the docs

Because each domain's .yaml already declares both the local and staging CoreAPI as servers:

servers:
  - url: http://localhost:3000
    description: Local development (direct to CoreAPI)
  - url: https://stag.api.castis.io/
    description: Staging CoreAPI server

...you can use the docs site itself to actually call your running CoreAPI and test endpoints interactively — pick the localhost:3000 server in the dropdown, fill in the request body/params from the spec, and hit "Execute." Once your endpoint is documented in the .yaml, you get a working test client for free, without needing a separate Postman collection or manual curl commands for every case.

Documenting changes to pkg/

Not every change lives inside a domain — sometimes you're adding or changing something in CoreAPI's pkg/ (shared packages like jwt, email, StreamerClient, CProxyClient, etc.), which isn't an API domain and doesn't have its own OpenAPI spec.

The docs repo already has a home for this — docs/pkg/. Each package that's documented gets its own folder with just an index.md (and a changelog.md if it's changed enough times to be worth tracking), e.g. docs/pkg/StreamerClient/index.md. There's no .yaml spec here since pkg/ isn't a set of HTTP routes.

If you add or meaningfully change something in pkg/ that other devs would need to know about (a new client, a changed method signature, a new config option), you don't need to build anything new — just:

  1. Add a folder for it under docs/pkg/<package-name>/ if one doesn't already exist.
  2. Write an index.md describing what it does and how to use it (add a changelog.md too if you expect it to change again later).

That's it — it'll pick up the same nav/site structure as the other pkg/ entries automatically.