Consider different approach/plugin for rendering API documentation

p2-inc / phasetwo-docs

docusaurus repo for phasetwo.io public website and documentation

1 stars 11 forks source link

Consider different approach/plugin for rendering API documentation #88

Closed xgp closed 1 year ago

xgp commented 1 year ago

The docusaurus openapi plugin we use has many bugs and isn't well-maintained https://github.com/cloud-annotations/docusaurus-openapi

Consider using vanilla swagger UI for API docs:

in a separate github pages repo: https://github.com/peter-evans/swagger-github-pages
as a react component inside src/pages/api.js https://www.npmjs.com/package/swagger-ui-react

xgp commented 1 year ago

Because of an incompatibility, the current plugin we use also prohibits us from upgrading docusaurus.

hisorange commented 1 year ago

Let me give a +1 to this. Just opened a silly ticket in the org plugin repo because the UI was a bit misleading.

Please see the image below, the response header which would tell the programmer that the resource will be identified at the new location is missing from the UI, is missing (green) Screenshot 2023-03-12 at 14 11 45

But it is defined, and even well documented on the standard Swagger UI. Screenshot 2023-03-12 at 14 12 22

And the same goes for the attributes there is a helpful documentation which shows the values are a string array.

xgp commented 1 year ago

We switched to this plugin https://github.com/PaloAltoNetworks/docusaurus-openapi-docs Seems to have fewer bugs and sensible defaults.