feat: add support for vendor extension renderers #2545

weyert · 2024-03-11T12:52:36Z

Adds support for defining vendor extension renderers in @stoplight/elements so vendor extensions throughout a OpenAPI specification can be visually renderer.

Elements Default PR Template

In general, make sure you have: (check the boxes to acknowledge you've followed this template)

Read CONTRIBUTING.md

weyert · 2024-03-11T12:54:00Z

packages/elements-core/src/components/Docs/HttpOperation/Body.tsx

@@ -23,7 +24,7 @@ export const isBodyEmpty = (body?: BodyProps['body']) => {
  return contents.length === 0 && !description?.trim();
 };

-export const Body = ({ body, onChange }: BodyProps) => {
+export const Body = ({ body, onChange, renderExtensionAddon }: BodyProps) => {
  const [refResolver, maxRefDepth] = useSchemaInlineRefResolver();
  const [chosenContent, setChosenContent] = React.useState(0);
  const { nodeHasChanged } = useOptionsCtx();


Currently, I am pulling through the renderExtensionAddon-property in each relevant component. I was wondering if I should get it from useOptionsCtx()-hook instead?

Please advise what your expected or preferred approach is

This PR is great! We are super excited about this.

We would prefer that you add it to the useOptionsCtx()

Additionally could you create a elements type to replace the import { ExtensionAddonRenderer } from '@stoplight/json-schema-viewer'; so we are not dependent on the json-schema-viewer implementation? Also please add tests and storybook example.

Thank you @brendarearden. I hope to pick up end of next week and make the requested changes.

I also would like to introduce the functionality to expand/collapse all properties of a schema. Only I don't know yet what the best approach to achieve this.

I believe you would be able to utilize the expandedDepth from the SchemaTreeOptions in json-schema-viewer to achieve that functionality. If you do decide to introduce that, it would be preferable to have a separate PR from this one.

Yeah, definitely in a new PR for that one. I think the main issue I saw that the expansion state is stored in RowSchemaRow-component but probably better to discuss the json-schema-viewer-repo first. Probably worth to add the expandAll/collapseAll-functionality there first.

Going to pick up this PR soon. A few work stuff that is more important but after that I am going to do some Elements related work so expect work on this PR and maybe this expandAll/collapseAll-functionality

hey @weyert are you planning on continuing this work?

Next week 👍

@daniel-white Am I blocking you?

@daniel-white @brendarearden Would be fine to import SchemaNode from the @stoplight/json-schema-tree-package?

netlify · 2024-03-11T12:54:33Z

✅ Deploy Preview for stoplight-elements-demo ready!

Name	Link
🔨 Latest commit	`2cf6338`
🔍 Latest deploy log	https://app.netlify.com/sites/stoplight-elements-demo/deploys/6628d36bc69efc0008cb7032
😎 Deploy Preview	https://deploy-preview-2545--stoplight-elements-demo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify · 2024-03-11T12:54:37Z

✅ Deploy Preview for stoplight-elements ready!

Name	Link
🔨 Latest commit	`2cf6338`
🔍 Latest deploy log	https://app.netlify.com/sites/stoplight-elements/deploys/6628d36b0409e700081931f5
😎 Deploy Preview	https://deploy-preview-2545--stoplight-elements.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

# Conflicts: # packages/elements-dev-portal/package.json # packages/elements/package.json

weyert · 2024-04-22T16:15:29Z

@daniel-white @brendarearden I have updated the PR based on your feedback

weyert · 2024-04-22T16:16:03Z

packages/elements-core/src/__fixtures__/articles/kitchen-sink.md

+            "type": {
+              "type": "string",
+              "enum": ["STANDARD", "ADMIN"],
+              "x-enum-descriptions": {


Updated a bunch of fixtures, like this, one to accommodate for testing vendor extensions functionality both in Storybook and unit tests

weyert · 2024-04-22T16:18:21Z

packages/elements-core/src/components/Docs/Model/Model.spec.tsx

@@ -16,6 +18,10 @@ const exampleSchema: JSONSchema7 = {
    propA: {
      type: 'string',
      enum: ['valueA'],
+      // @ts-ignore
+      'x-enum-descriptions': {


For some reason JSONSchema7 don't support vendor extensions. It's probably a OpenAPI enhancement for JSON. schema?
I am not sure if that's expected but that is the reason for the @ts-ignore.

weyert · 2024-04-22T16:18:50Z

packages/elements-core/src/components/Docs/story-renderer-helper.tsx

+  }
+
+  // This implementation of the extension renderer only supports the `x-enum-descriptions`-extension
+  if ('x-enum-descriptions' in vendorExtensions) {


Just a simple implementation of a vendor extension

weyert · 2024-04-22T16:19:32Z

packages/elements-core/src/components/MarkdownViewer/CustomComponents/CodeComponent.tsx

@@ -40,6 +41,8 @@ interface ISchemaAndDescriptionProps {

 const SchemaAndDescription = ({ title: titleProp, schema }: ISchemaAndDescriptionProps) => {
  const [resolveRef, maxRefDepth] = useSchemaInlineRefResolver();
+  const { renderExtensionAddon } = useOptionsCtx();


Updated to allow schemas referred in the Article-component also work with the vendor extension renderers

weyert · 2024-04-22T16:20:35Z

packages/elements/src/components/API/APIWithResponsiveSidebarLayout.tsx

-          tryItCredentialsPolicy={tryItCredentialsPolicy}
-          tryItCorsProxy={tryItCorsProxy}
-        />
+        <ElementsOptionsProvider renderExtensionAddon={renderExtensionAddon}>


For some reason the API* components don't see to wrap around the ElementsOptionsProvider. This is required to be able to use useOptionsCtx in elements-core.

I appreciate some guidance if this the right approach you had in mind.

weyert · 2024-04-22T16:22:43Z

Storybook renditions below, note that both have the vendor extension renderer working for the x-enum-descriptions-extension

Article

HTTP operation

Changed the handling of vendor extensions to allow to render vendor extensions in the body of a `Model` or `HttpOperation` between the title and the request block

weyert · 2024-04-24T16:55:39Z

@brendarearden @daniel-white I am assigned this week to do work related to Elements. Would love to get some feedback on this PR.

brendarearden · 2024-04-26T18:00:47Z

@weyert due to the size of this PR, we will have to dedicate specific time in our work flow to review this. We have added an issue for this work to our backlog and will prioritize it.

weyert · 2024-04-26T18:48:19Z

@weyert due to the size of this PR, we will have to dedicate specific time in our work flow to review this. We have added an issue for this work to our backlog and will prioritize it.

Okay, then I will try to make a small enhancement to it that we would like to have internally. We think it would be useful to also have access to the schema-level vendor extensions when rendering a property of the schema and then always call the renderer when at least one of the two are not empty.

As we would like to render a marking when the property is expandable but define it on the schema level instead of x-expandableField-extension per property.

On another topic I would love to be able to email with someone about the allOf merging behaviour of Elements or json-schema-tree so we can fix some issues related to it but that code is a bit difficult to follow

feat: add support for vendor extension renderers

667c47f

weyert commented Mar 11, 2024

View reviewed changes

weyert added 2 commits April 22, 2024 10:20

chore: Merge branch 'main' into add-vender-extensions-support

864d741

# Conflicts: # packages/elements-dev-portal/package.json # packages/elements/package.json

fix: update the code based on PR feedback

8947d6c

weyert commented Apr 22, 2024

View reviewed changes

style: resolve linting issues

669fc54

weyert marked this pull request as ready for review April 22, 2024 16:26

weyert requested a review from a team as a code owner April 22, 2024 16:26

weyert requested a review from mallachari April 22, 2024 16:26

weyert added 3 commits April 24, 2024 08:43

Merge branch 'main' into add-vender-extensions-support

7745751

Merge branch 'main' into add-vender-extensions-support

de22167

fix: add the ability to render vendor extensions in the body

2cf6338

Changed the handling of vendor extensions to allow to render vendor extensions in the body of a `Model` or `HttpOperation` between the title and the request block

weyert requested review from daniel-white and brendarearden April 24, 2024 09:40

weyert mentioned this pull request May 20, 2024

feat: add ability to override code examples using x-codeSamples #2574

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add support for vendor extension renderers #2545

feat: add support for vendor extension renderers #2545

weyert commented Mar 11, 2024

weyert Mar 11, 2024

brendarearden Mar 15, 2024

weyert Mar 16, 2024

brendarearden Mar 29, 2024

weyert Mar 29, 2024 •

edited

daniel-white Apr 12, 2024

weyert Apr 12, 2024

weyert Apr 13, 2024

weyert Apr 22, 2024

netlify bot commented Mar 11, 2024 •

edited

netlify bot commented Mar 11, 2024 •

edited

weyert commented Apr 22, 2024

weyert Apr 22, 2024

weyert Apr 22, 2024

weyert Apr 22, 2024

weyert Apr 22, 2024

weyert Apr 22, 2024

weyert commented Apr 22, 2024

weyert commented Apr 24, 2024

brendarearden commented Apr 26, 2024

weyert commented Apr 26, 2024 •

edited

feat: add support for vendor extension renderers #2545

Are you sure you want to change the base?

feat: add support for vendor extension renderers #2545

Conversation

weyert commented Mar 11, 2024

Elements Default PR Template

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weyert Mar 29, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Mar 11, 2024 • edited

✅ Deploy Preview for stoplight-elements-demo ready!

netlify bot commented Mar 11, 2024 • edited

✅ Deploy Preview for stoplight-elements ready!

weyert commented Apr 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weyert commented Apr 22, 2024

Article

HTTP operation

weyert commented Apr 24, 2024

brendarearden commented Apr 26, 2024

weyert commented Apr 26, 2024 • edited

weyert Mar 29, 2024 •

edited

netlify bot commented Mar 11, 2024 •

edited

netlify bot commented Mar 11, 2024 •

edited

weyert commented Apr 26, 2024 •

edited