Skip to content
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

Conversation

lucasassisrosa
Copy link
Contributor

@lucasassisrosa lucasassisrosa commented Jan 11, 2024

Description

This PR aims to fix the x-codeSamples integration. When x-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 when x-codeSamples is provided. I assumed it's better to add the custom code samples to the existing generated code samples in the list of variants

Motivation 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 highlighting

Types of changes

  • Bug fix (non-breaking change which fixes an issue)

Checklist

  • I have updated the documentation accordingly.
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes if appropriate.
  • All new and existing tests passed.

Copy link
Contributor Author

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

Copy link
Member

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"] ?? []}
Copy link
Contributor Author

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

Comment on lines 361 to 363
label={
lang.labels ? lang.labels[index] : variant.toUpperCase()
}
Copy link
Contributor Author

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

Copy link
Member

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?

Copy link
Contributor Author

@lucasassisrosa lucasassisrosa Jan 12, 2024

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

Copy link
Member

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.

Copy link
Contributor Author

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?

Copy link
Contributor Author

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

27f6376

Copy link
Member

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.

@lucasassisrosa lucasassisrosa changed the title add support to x-codeSamples Add support to x-codeSamples Jan 11, 2024
@@ -147,6 +147,7 @@ paths:
Console.WriteLine(response.getRawResponse());
}
- lang: PHP
label: Custom
Copy link
Contributor Author

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

Copy link

github-actions bot commented Jan 12, 2024

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 🌎

@sserrata
Copy link
Member

Hi @lucasassisrosa, I think this PR accomplishes the goal of supporting x-codeSamples. I think it's ready to merge as-is but I plan to follow up to address the issues pertaining to:

  • allowing users to specify which variants to include
  • allowing users to customize the order languages are rendered
  • allowing users to completely disable/hide the snippets component
  • allowing users to only show custom languages (i.e. hide generated)

@sserrata sserrata merged commit 8a42186 into PaloAltoNetworks:main Jan 18, 2024
13 checks passed
@lucasassisrosa lucasassisrosa deleted the DOTCOM-2863-support-custom-code-examples branch February 1, 2024 23:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants