publish-api-to-catalog

Skill: Publish API to Catalog

This is the canonical copy of amp-catalog/.claude/skills/publish-api-to-catalog/SKILL.md, mirrored into this orchestrator so it's available whenever working inside an api-cp-* repo without needing a local amp-catalog clone. Keep both in sync if either changes.

Onboards the current repository to the API Catalog stop-gap: a public Swagger UI site at https://hmcts.github.io/<repo>/, plus an automatic listing in amp-catalog.

The per-repo footprint is a single workflow file — most of this skill is checking the API is safe to expose and verifying the result.

Run these phases in order. Do not skip Phase 2.

Phase 1 — Locate and validate the OpenAPI spec

1. Confirm you are in an API repo (it has an OpenAPI spec). Find it:

   find . -path ./.git -prune -o -name "openapi-spec.y*ml" -print 2>/dev/null
   

   The HMCTS convention is src/main/resources/openapi/openapi-spec.yml. If there are several, ask the user which is the published spec.

2. Sanity-check it parses and read its info block (used later for the catalog entry):

   ruby -ryaml -e 'i=YAML.load_file(ARGV[0])["info"]; puts i["title"]; puts i["description"]' <SPEC_PATH>
   

   If it does not parse, stop and report — fix the spec first.

3. Check the servers block. SwaggerHub virtservers are no longer available; exposed APIs must use the standard server URL pattern, with the version matching the API version (info.version):

   servers:
     - description: <API title>
       url: https://<api_repo_name>.net/{version}
       variables:
         version:
           default: <info.version>
           description: API version; matches the spec info.version
   

   If the spec still points at virtserver.swaggerhub.com (or any other pattern), fix it as part of this onboarding — include it in the Phase 4 PR or open a separate chore: PR.

   The in-repo version is only a placeholder — do not hand-bump it. The real version is the GitHub release tag (without the v prefix), stamped in two places:

   • Release artefacts: hmcts/update-openapi-version (in ci-released.yml) re-stamps info.version and servers[0] with this same pattern.
   • Docs site: the shared publish-swagger-ui.yml workflow stamps the spec before deploying (release tag on release runs; latest v* tag via git describe on manual dispatch), so the published Swagger UI always shows the released version. Repos with no v* tag yet publish the committed placeholder until their first release.

4. Record the path relative to the repo root as OPENAPI_PATH.