smart-on-fhir / cumulus Goto Github PK

Right now, we're getting docs updates from the head of main, which means we may have documentation publicly available for features that have yet to be released.

It would be good to update this in some way to pull from the latest release in the target repos instead.

Both the aggregator and the dashboard are producing openAPI 3.0 specs for documenting the expected behavior of the endpoints they provide. It would be nice for the docsite to present these in a graphical way with off the shelf tools, so that we don't need to regenerate artifacts on change.

There are a few options
https://github.com/jonasob/the-open-api - this jekyll plugin is a lightweight version that does not provide the interactive 'test out a http request' mode, which is probably not what we're looking to do with our documentation anyway
https://www.npmjs.com/package/openapi-to-md - this would allow us to just render openapi docs as markdown, which would work well when viewed in github as well
https://swagger.io/tools/swagger-ui/ - there are docker images of the swagger UI available that we could spin up/redirect to

The goal here would be a single documentation rendering approach that would apply for any existing, or future, APIs we develop as part of Cumulus.