-
Notifications
You must be signed in to change notification settings - Fork 89
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
Enhance documentation UI #182
Conversation
Deploy preview for open-api ready! Built with commit 60a7f7a |
This is super awesome 🎉 |
Upgraded the logo (thanks @iKristy!). Looks much better now! |
Oof, bummer redirects won't work since those are all behind a hash. :( |
We can handle redirects client side.
|
redoc/build.js
Outdated
const redocCli = async function() { | ||
await pExecFile('redoc-cli', [ | ||
`--title=${TITLE}`, | ||
`--options.expandResponses=${SUCCESS_STATUS_CODES}`, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thoughts on disabling this?
When 200 response are auto expanded by default it makes scrolling much much longer.
I tried the build with this line commented out and it was easier to quickly scroll down the page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed in 275ecc4
0094206
to
55239b4
Compare
6182ee5
to
81cff8f
Compare
I've added the following:
The endpoints are also now grouped by models. The models themselves are grouped when they are related. When it comes to the links (that you mentioned above), I've opened netlify/cli#546 to update the links of I have removed all the code related to the previous setup (based on Swagger UI). Finally I made the following refactoring changes:
I need some feedback on the following:
|
b8d482f
to
fb28d87
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sections copied from the online documentation: "Making a request", "Authenticating", "Rate limiting", "Pagination", "Site IDs"
Please remove these. Keeping identical docs in two places in an anti-pattern and will lead to drift. The copied text is already out of sync with an updated version of the text currently in a PR for docs 2.0 migration.
fb28d87
to
30ec206
Compare
@verythorough fixed! Is there anything left because this can be deployed to production? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for fixing the cli links with netlify/cli#546!
Could you add the JS redirect as @DavidWells suggested? That way links that we can't account for (in blog posts, etc.) will still work, too.
Otherwise, I think the tags/tag groups you chose work fine, and this is a nice improvement on what was there before. Looking forward to working on our next iteration!
c97af96
to
60a7f7a
Compare
Oh I did not understand @DavidWells comment on the redirects, I get it now. Very good point! I've fixed it in 60a7f7a You can try for example https://deploy-preview-182--open-api.netlify.com/#/default/listSites Ready for another round :) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Awesome! Works great for me! 🚀
Fixes #172
This changes the HTML/CSS of the OpenAPI documentation using
redoc
instead ofswagger-ui
.Before (screenshot)
After (screenshot)
Before (URL): https://5d7672277da50b0008d42dda--open-api.netlify.com
After (URL): https://deploy-preview-182--open-api.netlify.com
Improvements over previous setup:
Not changed:
To be done:
redoc
does everything. I can do the cleanup after this PR is merged.