chore(docs): add docusaurus-plugin-openapi-docs and docusaurus-theme-openapi-docs
#109
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
b-long
force-pushed
the
chore/add-docusaurus-theme-openapi-docs
branch
4 times, most recently
from
b54d3e7 to
10f1cfa
Compare
Contributor
Author
b-long
changed the title
docusaurus-theme-openapi-docsdocusaurus-plugin-openapi-docs and docusaurus-theme-openapi-docs
b-long
force-pushed
the
chore/add-docusaurus-theme-openapi-docs
branch
2 times, most recently
from
41cac66 to
d49d6fc
Compare
b-long
force-pushed
the
chore/add-docusaurus-theme-openapi-docs
branch
from
d49d6fc to
01a268c
Compare
b-long
force-pushed
the
chore/add-docusaurus-theme-openapi-docs
branch
from
01a268c to
5895cb1
Compare
3 tasks
Contributor
Author
|
Replaced by #110 |
b-long
added a commit
that referenced
this pull request
Jun 13, 2025
This PR is a recreation of #109 . ## Description The goal of this PR is to enrich our docusaurus site, by adding [`docusaurus-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs) and using it to embed OpenAPI/Swagger generated content. In this PR, we are vendoring the OpenAPI (YAML) files, which are found in OpenTDF ( [here](https://github.com/opentdf/platform/tree/main/docs/openapi) ). ## Reviewing this PR To generate the site for a typical deployment, build and start the site as follows: ``` # Set env var, or simply skip it export BUILD_OPENAPI_SAMPLES=0 rm -rf docs/SDK-OpenAPI/ docs/SDK-Samples/ specs-processed/ npm run gen-api-docs-clean && npm run gen-api-docs-all npm run start ``` To generate the site including "art of the possible" (petstore & bookstore examples), build and start the site as follows: ``` export BUILD_OPENAPI_SAMPLES=1 rm -rf docs/SDK-OpenAPI/ docs/SDK-Samples/ specs-processed/ npm run gen-api-docs-clean && npm run gen-api-docs-all npm run start ``` ### Video 2 (loom) https://www.loom.com/share/522b0eb6b2d34793ba555b1ca3a31722 ### Video 1 <details><summary>Click to show</summary> <p> https://github.com/user-attachments/assets/25f22aed-5ba5-4a4f-bd76-17acc5daf2df </p> </details> ### To-do - [ ] Determine if we need to run `npm run gen-api-docs-all` (explicitly) for CI and/or production builds. In other words, does this happen automatically? ### Defer / New Jira tickets - [x] Revert [Disable false-positive machine](d228655) / figure out the right way to tune Vale ➡️ recommend a new Jira ticket / PR - [ ] Use remote OpenAPI definition files? ➡️ recommend a new Jira ticket / PR ### Vale If I were king for a day, I'd just remove this tool. <details><summary>It's pretty unclear (to me) how to improve the configuration quality</summary> <p> <img width="1495" alt="image" src="https://github.com/user-attachments/assets/6e22dcc3-7b2e-4c47-bed7-040ee58137d9" /> </p> </details> <details><summary>It's complaining about files that are untouched / unmodified in this PR</summary> <p> <img width="1495" alt="image" src="https://github.com/user-attachments/assets/c2908677-e306-4d74-8511-ac1bf1652715" /> </p> </details> <details><summary>And some part of it's machinery / reviewdog thinks we have too much content to process... which seems tricky, because clearly we will have large diffs if we intend to version generated content.</summary> <p> <img width="1495" alt="image" src="https://github.com/user-attachments/assets/2ee4786d-24af-45ba-bbaa-2acecfafd97f" /> </p> </details>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The goal of this PR is to enrich our docusaurus site, by adding
docusaurus-openapi-docsand using it to embed OpenAPI/Swagger generated content.Inspired by opentdf/platform#2366
Video ( rough / work-in-progress ♻️ )
Screen.Recording.2025-06-06.at.12.22.12.PM.mov
Context / background
docusaurus-openapi-docs. Details about this are in Slack conversation with @cassandrabailey293 @strantalis , and @jrschumacher.protofiles, but am waiting to hear back about that work.docusaurus-openapi-docsYAMLfiles match a particular release (e.g. https://github.com/opentdf/platform/releases/tag/service%2Fv0.6.0 )docusaurus-openapi-docs, which may be irrelevant or innappropriate for the upstream https://github.com/opentdf/platformThings that need to be done / un-done
npm run gen-api-docs-all(explicitly) for CI builds. In other words, does this happen automatically?npm run gen-api-docs-all(explicitly) for production builds. In other words, does this happen automatically?