[paynejd]

A Swagger page for the FHIR terminology service

Follows #956 and is stacked on its branch; it gets retargeted to master once #956 merges. Tracking: OpenConceptLab/ocl_online#451.

Why: when FHIR has its own host (FHIR_SUBDOMAIN), the API host answers FHIR paths with a 404. Today's Swagger page still lists them, each up to four times (with and without a trailing slash, plus malformed forms such as /fhir/CodeSystem$lookup), with write methods FHIR doesn't serve and internal docstrings. "Try it out" on them fails.

What changes

• The FHIR host serves its own Swagger page: /swagger/, /swagger.json and /swagger.yaml. It describes the FHIR terminology service alone, and "Try it out" calls that host.
  • What it lists: search and read of CodeSystem, ValueSet and ConceptMap; $lookup; CodeSystem and ValueSet $validate-code; $expand; $translate; metadata; and $versions. Each is listed at /fhir and at the owner bases /orgs/{org} and /users/{user}.
  • How it lists them: each operation appears once, with no trailing slash, tagged CodeSystem, ValueSet, ConceptMap or Capabilities. Each has its query parameters, a Parameters body for POST, and OperationOutcome errors.
  • What it leaves out: PUT, PATCH, DELETE, create by POST, and the duplicate path forms.
  • The parameter descriptions follow the code. For example, they say which separate inputs a coding replaces.
• The API's Swagger page:
  • When FHIR has its own host, the API's page leaves the FHIR paths out and links to the FHIR page.
  • When FHIR shares the host, the API's page lists the same curated operations instead of the generated ones.
  • Every other API path and operation is unchanged; a test compares them with the generator's previous output.
• FhirMiddleware: it opens only the three documentation paths on the FHIR host. The Swagger UI's static files are served ahead of it, as they are today, and the middleware order is unchanged.
• Authorize: operations inherit the existing Token and Basic definitions, so Swagger's Authorize button works at owner bases, where a token shows private content.

Testing

• Full suite on the final commit: 3,463 tests OK, pylint 10.00/10, coverage 96% (99% in core/fhir).
• New tests in core/fhir/tests_swagger.py:
  • the exact (method, path) set, each resolved against the URL conf;
  • search parameters taken from the search parser;
  • operation parameters and POST bodies;
  • which inputs a coding replaces;
  • the FHIR host's paths, and the order of static files ahead of the host check;
  • the API page with FHIR on its own host and on the same host;
  • the unchanged non-FHIR operations.
• Not changed here: python manage.py generate_swagger already fails on master, in a bulk-import view, so this PR leaves it alone. The HTTP schema endpoints work.

Review

Codex reviewed it in three passes. Passes 1 and 2 each found a description that over-promised what an input does alongside a coding, and both are fixed; pass 3 was clean. A simplification review proposed one cut, which was declined.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R8hw7w8753DDSCezrmrDA8

[paynejd]

Review loop (Codex passes 1–3, simplification)

• Codex pass 1 (codex-cli 0.163.0, commit 9d754f7): one P1, fixed in e06ba67. The schema implied that a separate display, systemVersion or version still applies when coding is given, which the operations don't do. Each operation's coding now names the inputs it replaces, and those inputs say they aren't read alongside a coding.
• Codex pass 2 (commit e06ba67): one P1, fixed in 6bf3ea6. $lookup's system is still checked at an instance, so it now says that it must name that code system there.
• Codex pass 3 (commit 6bf3ea6): clean, with both findings resolved.
• Simplification review: one cut proposed (a deepcopy of parameter lists) and declined. It saves no lines, and the copy keeps the shared parameter objects unmutated.
• Full gate on 6bf3ea6: 3,463 tests OK, pylint 10.00, coverage 96%.

The full findings are on the tracking ticket.