Serving OpenAPI Specs - #38093
Draft
kaapstorm wants to merge 5 commits into
Draft
Conversation
yarn build now produces one Redoc page per generated spec into docs/api/dist/, which is gitignored: deployed environments build static assets as a required step, so committing roughly 3MB of generated HTML would buy nothing that the committed specs do not already give us. Chaining it onto yarn build rather than adding a separate CI step is what makes that true everywhere the assets are built -- the Build Static Files job and a production deploy alike -- instead of only where a workflow remembers to ask for it. build-static.yml says so in its progress line. DEV_SETUP explains that a local checkout needs the build before those pages work, since yarn dev does not run it.
The views that publish the specs and the command that writes them need the same notion of where the artifacts live. Defining it once means they cannot disagree. Also computes description coverage per spec, so the reference index can show which APIs are fully documented and which are only structurally generated. Coverage resolves $ref and descends anyOf/oneOf/allOf branches rather than reading schema['properties'] directly: case-v2's detail response is an anyOf whose first branch carries 14 fields, and a direct read would count none of them, publishing a denominator that understated the API's real surface.
/api/openapi.json serves the bundle and /api/docs/<slug>/openapi.json serves one API's spec, with /.well-known/openapi.json as a discovery alias. The well-known path is a de facto convention, not an IANA-registered URI. Each response carries the requesting host as the servers default, so a client that follows it reaches the deployment it fetched the spec from rather than www.commcarehq.org. The ETag covers the host as well as the file contents, because the served bytes differ per host.
Rendered from the catalogue at request time rather than generated, so it cannot drift from what is actually documented, and a new API appears with no build step. It also shows how completely each API is described, which makes the remaining documentation work visible instead of something a reader has to be told.
An unknown slug is rejected against the catalogue rather than the filesystem. A missing artifact names the build command under DEBUG and logs a warning otherwise, because in a deployed environment it means the asset build did not run.
dimagimon
added
dependencies
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Technical Summary
Serves the OpenAPI specs generated by PR #38092
Feature Flag
Safety Assurance
Safety story
Automated test coverage
QA Plan
Migrations
RemoveField,RenameField,RemoveConstraint, and others described here that can cause errors when migrations are applied to a live database.Rollback instructions
Labels & Review