Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SPIKE: rendering of openapi definitions #22

Open
dogversioning opened this issue Feb 23, 2024 · 1 comment
Open

SPIKE: rendering of openapi definitions #22

dogversioning opened this issue Feb 23, 2024 · 1 comment
Labels
documentation Improvements or additions to documentation

Comments

@dogversioning
Copy link
Contributor

dogversioning commented Feb 23, 2024

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.

@dogversioning
Copy link
Contributor Author

@vlad-ignatov this is trying to capture the discussion from yesterday - feel free to add notes/other proposals.

@dogversioning dogversioning reopened this Feb 23, 2024
@mikix mikix added the documentation Improvements or additions to documentation label Apr 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants