feat: add support for message.examples (#176)

Author: derberg

.github/workflows/release.yml

@@ -46,9 +46,9 @@ jobs:
       # Web-component
       - name: Install latest version of library in the web-component # this will update package.json and a lock file for the web-component that will also be pushed to PR with next step
         if: steps.initversion.outputs.version != steps.extractver.outputs.version
-        # sleep for 10 seconds before using latest version in web-component, because sometimes NPM needs additional few seconds to `saves` package in registry
+        # sleep for 20 seconds before using latest version in web-component, because sometimes NPM needs additional few seconds to `saves` package in registry
         run: |
-          sleep 10
+          sleep 20
           npm install @kyma-project/asyncapi-react@${{ steps.extractver.outputs.version }} -s
         working-directory: ./web-component
       - name: Build web-component

library/src/containers/Messages/Message.tsx

@@ -3,7 +3,11 @@ import React from 'react';
 import { SchemaComponent } from '../Schemas/Schema';
 import { PayloadComponent } from './Payload';
 
-import { bemClasses, removeSpecialChars } from '../../helpers';
+import {
+  bemClasses,
+  removeSpecialChars,
+  getExamplesFromSpec,
+} from '../../helpers';
 import { Message, isRawMessage } from '../../types';
 
 import { Markdown, Badge, BadgeType, Toggle } from '../../components';
@@ -72,6 +76,7 @@ export const MessageComponent: React.FunctionComponent<Props> = ({
   }
 
   title = title || message.title || message.name;
+  const examples = message.examples;
 
   const summary = message.summary && (
     <div className={bemClasses.element(`${className}-summary`)}>
@@ -108,6 +113,7 @@ export const MessageComponent: React.FunctionComponent<Props> = ({
   const headersID = !inChannel
     ? bemClasses.identifier([{ id: messageID, toKebabCase: false }, 'headers'])
     : undefined;
+
   const headers = message.headers && (
     <section
       className={bemClasses.element(`${className}-headers`)}
@@ -123,6 +129,7 @@ export const MessageComponent: React.FunctionComponent<Props> = ({
           schema={message.headers}
           exampleTitle={HEADERS_EXAMPLE_TEXT}
           hideTitle={true}
+          examples={examples && getExamplesFromSpec(examples, 'headers')}
         />
       </div>
     </section>
@@ -142,6 +149,7 @@ export const MessageComponent: React.FunctionComponent<Props> = ({
       payload={message.payload}
       identifier={payloadID}
       dataIdentifier={payloadDataID}
+      examples={examples && getExamplesFromSpec(examples, 'payload')}
     />
   );
 

library/src/containers/Messages/Payload.tsx

@@ -19,6 +19,7 @@ interface Props extends Required<Pick<RawMessage, 'payload'>> {
   identifier?: string;
   dataIdentifier?: string;
   id?: number;
+  examples?: object[];
 }
 
 export const PayloadComponent: React.FunctionComponent<Props> = ({
@@ -28,6 +29,7 @@ export const PayloadComponent: React.FunctionComponent<Props> = ({
   identifier,
   dataIdentifier,
   id,
+  examples,
 }) => {
   const className = `message-payload`;
   const payloadsID = identifier ? `${identifier}s` : undefined;
@@ -54,6 +56,7 @@ export const PayloadComponent: React.FunctionComponent<Props> = ({
                 oneOf={true}
                 identifier={identifier}
                 id={index}
+                examples={examples}
               />
             </li>
           ))}
@@ -84,6 +87,7 @@ export const PayloadComponent: React.FunctionComponent<Props> = ({
                 anyOf={true}
                 identifier={identifier}
                 id={index}
+                examples={examples}
               />
             </li>
           ))}
@@ -105,6 +109,7 @@ export const PayloadComponent: React.FunctionComponent<Props> = ({
         schema={payload}
         exampleTitle={PAYLOAD_EXAMPLE_TEXT}
         hideTitle={true}
+        examples={examples}
       />
     </div>
   );

library/src/containers/Schemas/Schema.tsx

@@ -20,6 +20,7 @@ interface Props {
   hideTitle?: boolean;
   toggle?: boolean;
   toggleExpand?: boolean;
+  examples?: object[];
 }
 
 const renderSchemaProps = (
@@ -52,6 +53,7 @@ export const SchemaComponent: React.FunctionComponent<Props> = ({
   hideTitle = false,
   toggle = false,
   toggleExpand = false,
+  examples = [],
 }) => {
   if (!schema) {
     return null;
@@ -68,14 +70,22 @@ export const SchemaComponent: React.FunctionComponent<Props> = ({
       </span>
     </h3>
   );
-
+  const hasExamples = examples.length;
   const content = (
     <>
       <div className={`${bemClasses.element(`${className}-table`)} p-4`}>
         {renderSchemaProps(name, schema)}
       </div>
-      {/* we need to disable this component if schema has "not" field anywhere in it */}
-      {hasNotField ? null : (
+
+      {hasExamples ? (
+        examples.map((el, i) => (
+          <SchemaExampleComponent
+            title={hasExamples > 1 ? `${exampleTitle} ${i}` : exampleTitle}
+            example={el}
+            key={i}
+          />
+        )) // we need to disable this component if schema has "not" field anywhere in it
+      ) : hasNotField ? null : (
         <SchemaExampleComponent title={exampleTitle} schema={schema} />
       )}
     </>

library/src/containers/Schemas/SchemaExample.tsx

@@ -8,33 +8,35 @@ import { SCHEMA_EXAMPLE_TEXT } from '../../constants';
 
 interface Props {
   title?: string;
-  schema: Schema;
+  schema?: Schema;
+  example?: object;
 }
 
 export const SchemaExampleComponent: React.FunctionComponent<Props> = ({
   title,
   schema,
+  example,
 }) => {
-  const example = JSON.stringify(
-    schema.example ? schema.example : generateExampleSchema(schema),
-    null,
-    2,
-  );
+  const schemaExample =
+    schema && schema.example
+      ? schema.example
+      : schema && generateExampleSchema(schema);
+  const exampleString = JSON.stringify(example || schemaExample || '', null, 2);
 
-  if (!example) {
+  if (!exampleString) {
     return null;
   }
 
   return (
     <div className={bemClasses.element(`schema-example`)}>
       <CodeComponent
-        code={example}
+        code={exampleString}
         title={
           <div className={bemClasses.element(`schema-example-header`)}>
             <span className={bemClasses.element(`schema-example-header-title`)}>
               {title ? title : SCHEMA_EXAMPLE_TEXT}
             </span>
-            {schema.example ? null : (
+            {example || (schema && schema.example) ? null : (
               <div
                 className={bemClasses.element(
                   `schema-example-header-generated-badge`,

library/src/helpers/__tests__/getExamplesFromSpec.test.ts

@@ -0,0 +1,93 @@
+import { getExamplesFromSpec } from '../getExamplesFromSpec';
+
+describe('getExamplesFromSpec', () => {
+  test('should return headers', () => {
+    const result = getExamplesFromSpec(
+      [
+        {
+          headers: {
+            header1: 1,
+          },
+          payload: {
+            prop1: 1,
+          },
+        },
+        {
+          headers: {
+            header2: 2,
+          },
+          payload: {
+            prop2: 2,
+          },
+        },
+      ],
+      'headers',
+    );
+    expect(result).toEqual([
+      {
+        header1: 1,
+      },
+      {
+        header2: 2,
+      },
+    ]);
+  });
+
+  test('should return payload', () => {
+    const result = getExamplesFromSpec(
+      [
+        {
+          headers: {
+            header1: 1,
+          },
+          payload: {
+            prop1: 1,
+          },
+        },
+        {
+          headers: {
+            header2: 2,
+          },
+          payload: {
+            prop2: 2,
+          },
+        },
+      ],
+      'payload',
+    );
+    expect(result).toEqual([
+      {
+        prop1: 1,
+      },
+      {
+        prop2: 2,
+      },
+    ]);
+  });
+
+  test('should return payload and no undefined', () => {
+    const result = getExamplesFromSpec(
+      [
+        {
+          headers: {
+            header1: 1,
+          },
+          payload: {
+            prop1: 1,
+          },
+        },
+        {
+          headers: {
+            header2: 2,
+          },
+        },
+      ],
+      'payload',
+    );
+    expect(result).toEqual([
+      {
+        prop1: 1,
+      },
+    ]);
+  });
+});

library/src/helpers/getExamplesFromSpec.ts

@@ -0,0 +1,6 @@
+import { Example } from '../types';
+
+export type Type = 'payload' | 'headers';
+
+export const getExamplesFromSpec = (examples: Example[], type: Type) =>
+  (examples.map(el => el[type]).filter(Boolean) as any) as object[];

library/src/helpers/index.ts

@@ -10,3 +10,4 @@ export * from './stateHelpers';
 export * from './parser';
 export * from './removeSpecialChars';
 export * from './toKebabCase';
+export * from './getExamplesFromSpec';

library/src/types.ts

@@ -209,7 +209,7 @@ export interface RawMessage {
   description?: DescriptionHTML;
   externalDocs?: ExternalDocs;
   deprecated?: boolean;
-  examples?: any[];
+  examples?: Example[];
   protocolInfo?: any;
   traits?: MessageTrait | [MessageTrait, any];
 }
@@ -242,10 +242,15 @@ export interface MessageTrait {
   description?: DescriptionHTML;
   externalDocs?: ExternalDocs;
   deprecated?: boolean;
-  examples?: any[];
+  examples?: Example[];
   protocolInfo?: Record<string, any>;
 }
 
+export interface Example {
+  headers?: object;
+  payload?: object;
+}
+
 export interface Components {
   schemas?: Record<string, Schema>;
   messages?: Record<string, Message>;