CNP API Docs

The central OpenAPI registry for CFT. Every service publishes its spec here from its own pipeline, and the site renders them at https://hmcts.github.io/cnp-api-docs/: a searchable list of specs, a low level design page per product, C4 architecture views, and a registry health report.

Publishing a spec is all that is needed to appear — see Publish Swagger docs.

How it fits together

Path	What it is
docs/specs/*.json	Published specs. Written by other repos' pipelines; the only thing in this repo other teams write to.
registry.yaml	The facts that cannot be derived from a spec: product membership, dependency edges, curated names, prose. Hand-maintained.
model/build.mjs	Joins the two, plus Backstage ownership, into model/model.json.
c4/	LikeC4 sources. generated.c4 is derived from the model; views.c4 is hand-written.
site/	Astro site, built from model.json.
bin/	Build and validation scripts, plus the legacy publish scripts.

docs/ holds only two things now: the published specs, and the six C4 images that other repos' READMEs hotlink from master (bin/export-readme-pngs.mjs keeps those current). Everything else there — the vis.js graph, the Swagger UI bundles, microservices.json, the generated LLD pages — was the previous site and has been removed.

Getting started

This repo uses Yarn 4 (Berry) with node-modules as the linker, and is a single Yarn workspace with the site in site/. The Yarn binary is committed to .yarn/releases/, so installs do not depend on a Corepack download.

corepack enable   # once per machine
yarn install

Running the portal locally

yarn dev

Builds the model, the site and the architecture diagrams, assembles the artifact and serves it at http://localhost:8080/cnp-api-docs/. This is byte-for-byte what gets deployed. Set PORT to use a different port.

The individual steps, if you need one on its own:

yarn build         # everything, without serving
yarn build-site    # model, then the Astro pages
yarn build-c4      # architecture diagrams
yarn assemble      # copies docs/specs verbatim, verifying every byte
yarn serve-site    # serve build/dist

yarn assemble refuses to produce a deployable tree if any spec's bytes change during the copy — those URLs are fetched at runtime by other services. The site is served under /cnp-api-docs/ to match GitHub Pages; visiting / redirects there.

For live reload while working on the pages:

yarn dev-site

That runs Astro's dev server, which does not copy docs/specs, so the API reference pages will not render — use yarn dev for those.

Testing

yarn test              # unit tests plus the consumer contract
yarn validate-specs    # classify every spec in docs/specs/

The hosted checks in the consumer contract are skipped by default. To verify the live URLs that other services depend on:

CHECK_HOSTED=1 node --test test/consumer-contract.test.mjs

Registry health

Publishers push straight to master, so validation cannot block a bad spec landing. yarn validate-specs classifies every spec and is reported on each push.

A broken spec is not repaired or chased here. It belongs to the team that published it, and only they can fix it: the usual cause is their pipeline writing an empty file when it cannot reach the running application. Restoring the previous file centrally would put back a spec describing an older version of the API and leave that pipeline just as broken. Broken specs simply show up in the health report until their owner republishes.

test/consumer-contract.test.mjs is the exception, and the one thing enforced: it pins the spec filenames fetched from outside this repo — by XUI at runtime, by the CCD and HMC F-125 acceptance tests, and by terraform when registering APIs into Azure API Management. Do not rename or delete those files.

Publish Swagger docs

Use the reusable workflow. It runs a test in your repo that writes the spec to a temporary file, then publishes it here:

# .github/workflows/publish-openapi.yml
name: Publish OpenAPI spec
on:
  push:
    branches: [master]

jobs:
  publish-openapi:
    uses: hmcts/workflow-publish-openapi-spec/.github/workflows/publish-openapi.yml@v1
    secrets:
      SWAGGER_PUBLISHER_API_TOKEN: ${{ secrets.SWAGGER_PUBLISHER_API_TOKEN }}
    with:
      test_to_run: 'uk.gov.hmcts.reform.<your>.openapi.OpenAPIPublisherTest'
      java_version: 21

The spec is published to docs/specs/<repo-name>.json and served at https://hmcts.github.io/cnp-api-docs/specs/<repo-name>.json.

Legacy shell scripts

The scripts in bin/ predate the reusable workflow and are still curl-piped by a handful of Jenkinsfile_CNP builds, so they remain supported. Do not use them for new services. They require GH_TOKEN, and a repository slug from TRAVIS_REPO_SLUG, GITHUB_REPOSITORY or (for the docker variant) GIT_URL — without one they exit non-zero rather than writing the spec to a bare docs/specs/.json. They also refuse to publish an empty spec, which is what used to silently overwrite good specs with 1-byte files.

Custom Swagger groups

A project can split its Swagger documentation into independent groups (for example v1_internal and v2_external). The reusable workflow publishes the default group only, so services with custom groups run a group-aware script and pass each group as an argument:

- run: |
    curl https://github.com/ghraw/hmcts/cnp-api-docs/master/bin/publish-swagger-docs-group-dockerless.sh > publish-swagger-docs.sh
    sh ./publish-swagger-docs.sh v1_internal v1_external v2_internal v2_external
  env:
    GH_TOKEN: ${{ secrets.SWAGGER_PUBLISHER_API_TOKEN }}

Each group is published as docs/specs/<repo>.<group>.json. A group whose spec comes back empty is skipped rather than published, so one failing group no longer overwrites a good spec with a 1-byte file.

Use publish-swagger-group-docs.sh instead if the spec has to be scraped from the running application; it expects docker-compose.yml and .env files as per the Spring Boot Template.