search

nesi / research-developer-cloud

https://support.cloud.nesi.org.nz/
2 stars 1 forks source link

Explore how best to present the API as a reference within these docs #6

Open ndjones opened 1 year ago

ndjones commented 1 year ago

Existing OpenStack API docs are generated/generable from each OpenStack project source code repository. These could be generated and embedded within this docs site as an API reference. see https://docs.openstack.org/yoga/api/index.html

ndjones commented 1 year ago

Could go for a fully featured interactive API site, to make it as friendly as possible for RSE devops users e.g. https://redocly.com/redoc/

ndjones commented 1 year ago

here's an example of what I think would be useful @junhuhnesi @lbrick - https://developers.citizenlab.co/ - that site uses redoc (above) to drop in a really nice API reference. we've also had a look at postman before, and it can generate API docs too. https://learning.postman.com/docs/publishing-your-api/documenting-your-api/ - there's a testing workspace here for anyone who wants to take a look https://app.getpostman.com/join-team?invite_code=80b649e76c386716ee319c699be116bf&target_code=adbb778109eef4d928e52292b4efe3b7

lbrick commented 1 year ago

I have used ReDoc documents in the past and I do really like them, as I understand its the same as a swagger endpoint. Reading the ReDoc stuff I can see it might require and endpoint to a swagger document to produce those nice API calls, which I assume is not on the Openstack endpoints.

I am looking at the postman one now to see if that doesn't require an endpoint to base its documentation on.