-
Notifications
You must be signed in to change notification settings - Fork 246
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
Add support to x-codeSamples #697
Add support to x-codeSamples #697
Conversation
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.
I didn't see any references to this file. Codebase was using languageSet
from @theme/ApiExplorer/CodeSnippets
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.
You're correct, I included that file as a maintainer reference for what languages/variants are available.
@@ -30,7 +30,7 @@ function ApiExplorer({ | |||
{item.method !== "event" && ( | |||
<CodeSnippets | |||
postman={postman} | |||
codeSamples={(item as any)["x-code-samples"] ?? []} | |||
codeSamples={(item as any)["x-codeSamples"] ?? []} |
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.
x-code-samples
is the deprecated one
label={ | ||
lang.labels ? lang.labels[index] : variant.toUpperCase() | ||
} |
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.
labels might be useful for future support of different variant values and labels
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.
Makes sense...will these labels effectively override the defaults if passed via docusaurus config to a "generated" language?
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.
yes they will, but they're not right now. Right now they're just overriding the defaults for code samples. This makes me think if it should be named specifically like codeSampleLabels
or if it should be removed. I may try to make it work for generated" language variants but I wanted to avoid increasing the scope of the PR
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.
Agreed...also, there is another issue with generated code snippet - if you try to rearrange the order it leads to some errors. Additionally, I had hoped to allow users to specify which variants they wanted to render, but that needs additional work.
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.
@sserrata with " rearrange the order" you mean in CodeSnippets languageSet
or in Docusaurus Config languageTabs
?
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.
@sserrata I have updated the code samples implementation to keep it split from variants, having two CodeTabs. Please let me know if that's accurate. I also though about hiding the Variants (auto generated) tabs if there are CodeSamples but I don't know if that's the path the framework wants to move forward
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.
@sserrata with " rearrange the order" you mean in CodeSnippets languageSet or in Docusaurus Config languageTabs?
Docusaurus config languageTabs, although that issue has been around for some time and is not related to your changes.
@@ -147,6 +147,7 @@ paths: | |||
Console.WriteLine(response.getRawResponse()); | |||
} | |||
- lang: PHP | |||
label: Custom |
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.
just to leave an example of custom label
Visit the preview URL for this PR (updated for commit 2d2a885): https://docusaurus-openapi-36b86--pr697-1jznl18d.web.app (expires Sat, 17 Feb 2024 15:09:07 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 |
Hi @lucasassisrosa, I think this PR accomplishes the goal of supporting
|
Description
This PR aims to fix the
x-codeSamples
integration. Whenx-codeSamples
are provided, add as a variant for the target supported language in the API Explorer. At first it seems that the code was aiming to only display the custom code sample whenx-codeSamples
is provided. I assumed it's better to add the custom code samples to the existing generated code samples in the list of variantsMotivation and Context
x-codeSamples
redoc extension was partially supported and breaking the rendering if loaded in API Explorer. Continues #589 (@joecrop I tried to continue the implementation but the codebase has changed considerably)How Has This Been Tested?
Go to http://localhost:3000/petstore/add-pet and check API Explorer code samples. It reflects the OpenAPI spec now on
x-codeSamples
, following syntax highlightingTypes of changes
Checklist