Skip to content

Evospin Docs

docs/api/ — API SOT tooling

evo-spin/ebit-docs

`docs/api/` — API SOT tooling¶

This directory closes the loop on the API single-source-of-truth chain: the live Nest Swagger registration is the upstream truth, and every other artefact is regenerated from it.

┌──────────────────────────┐   curl   ┌────────────────────────────────┐
│ Nest @ApiOperation, DTOs │ ───────► │ live Swagger UI                │
│ apps/api/src/main.ts     │          │ http://localhost:4000/swagger  │
│ apps/bo/src/main.ts      │          │ http://localhost:4003/swagger  │
└──────────────────────────┘          └──────────────┬─────────────────┘
                                                     │ swagger.json
                                                     ▼
                              ┌─────────────────────────────────────────┐
                              │ docs/api-reference/openapi/*.openapi.json│  ← raw spec, machine-readable
                              └────────┬────────────────────────────┬───┘
                                       │                            │
                       _gen.py         │                            │ openapi-to-postmanv2
                       (Python)        │                            │ (node)
                                       ▼                            ▼
                  ┌────────────────────────────┐   ┌────────────────────────────────────┐
                  │ docs/api-reference/        │   │ docs/api/postman/                  │
                  │  api.md / bo.md /          │   │  ebit-api.postman_collection.json  │
                  │  rt-events.md /            │   │  ebit-bo.postman_collection.json   │
                  │  auth-flow.md              │   │  ebit-environment.postman_*.json   │
                  └────────────────────────────┘   └────────────────────────────────────┘
                              │                                      │
                              └──────────────┬───────────────────────┘
                                             ▼
                            ┌────────────────────────────────────┐
                            │ docs/api/changelog.md              │  ← versioned narrative
                            │ docs/api/changelog-process.md      │
                            └────────────────────────────────────┘

A change to a Nest controller annotation propagates by re-running sync-postman.sh — no artefact in the chain is hand-edited. The CompoDoc tree under ../api-compodoc/ is a parallel SOT view (architectural / DI graph, refreshed separately).

Entry point for "how do I use this API?": ../api-reference/index.md. This page focuses on tooling (generators, Postman, refresh process).

Files in this directory¶

File	What's inside	Owned by
`README.md`	This file. Explains the SOT chain + refresh process.	docs
`changelog.md`	Versioned API changelog. v1.0.0 baseline = 2026-04-25.	api owners
`changelog-process.md`	Process guide for keeping the changelog up to date when API changes ship.	api owners
`sync-postman.sh`	One-shot refresh: pulls live Swagger, regenerates Postman, drafts a JSON diff for the changelog.	docs
`postman/ebit-api.postman_collection.json`	Postman v2.1 collection for the `api` app. 59 folders, 317 requests.	docs (autogen)
`postman/ebit-bo.postman_collection.json`	Postman v2.1 collection for the `bo` app. 15 folders, 58 requests.	docs (autogen)
`postman/ebit-environment.postman_environment.json`	Local-dev environment variables (`baseUrl`, `accessToken`, captcha bypass, etc.).	docs
`postman/ebit-production.postman_environment.json`	Production stub. All host/secret values are `{{TBD}}` placeholders.	SRE/platform
`_convert-openapi-to-postman.js`	Node script wrapping `openapi-to-postmanv2@5`. Called by `sync-postman.sh`.	docs
`_extract-endpoints.py`	Python helper — emits per-tag endpoint counts for the changelog.	docs

Refresh cheat-sheet¶

Run from repo root /home/ubuntu/ebit:

Artefact	Command
Raw OpenAPI JSON	`curl -fsS http://localhost:4000/swagger.json -o docs/api-reference/openapi/api.openapi.json` (same for `bo` on 4003)
Markdown reference (`api.md`, `bo.md`)	`python3 docs/api-reference/_gen.py`
Postman collections	`node docs/api/_convert-openapi-to-postman.js docs/api-reference/openapi/api.openapi.json docs/api/postman/ebit-api.postman_collection.json "ebit api (port 4000)"`
Everything in one shot	`./docs/api/sync-postman.sh`
CompoDoc browse tree	`./docs/api-compodoc/regenerate.sh`

The full process — including how to turn the resulting JSON diff into a changelog entry — is documented in changelog-process.md.