Response example generation for XML and CSV

README.md

@@ -251,6 +251,7 @@ You can use all of the following options with the standalone version of the <red
   * **path-only**: displays a path in the sidebar navigation item.
   * **id-only**: displays the operation id with a fallback to the path in the sidebar navigation item.
 * `showWebhookVerb` - when set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar.
+* `codeSamplesLanguages` - enables code sample generation for the provided list of languages.
 
 ### `<redoc>` theme object
 * `spacing`
@@ -324,6 +325,17 @@ You can use all of the following options with the standalone version of the <red
   * `backgroundColor`: '#263238'
   * `color`: '#ffffff'
 
+## Auto generated code samples
+A new parameter called `codeSamplesLanguages` was added to `options` Object to provide code sample generation. You can pass an array like this to enable all languages supported by the code generation:
+
+```javascript
+['json','xml']
+```
+
+Where `['json']` is provided by default.
+
+When the `x-codeSamples` and `x-code-samples` are not set, it will
+automatically generate the code samples based on the language(s) you set.
 -----------
 ## Development
 see [CONTRIBUTING.md](.github/CONTRIBUTING.md)

demo/playground/hmr-playground.tsx

@@ -11,6 +11,10 @@ const userUrl = window.location.search.match(/url=(.*)$/);
 const specUrl =
   (userUrl && userUrl[1]) || (swagger ? 'swagger.yaml' : big ? 'big-openapi.json' : 'openapi.yaml');
 
-const options: RedocRawOptions = { nativeScrollbars: false, maxDisplayedEnumValues: 3 };
+const options: RedocRawOptions = {
+  nativeScrollbars: false,
+  maxDisplayedEnumValues: 3,
+  codeSamplesLanguages: ['json', 'xml'],
+};
 
 render(<RedocStandalone specUrl={specUrl} options={options} />, document.getElementById('example'));

src/components/__tests__/__snapshots__/DiscriminatorDropdown.test.tsx.snap

@@ -76,6 +76,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
                   "minItems": undefined,
                   "options": RedocNormalizedOptions {
                     "allowedMdComponents": Object {},
+                    "codeSamplesLanguages": Array [
+                      "json",
+                    ],
                     "disableSearch": false,
                     "downloadDefinitionUrl": undefined,
                     "downloadFileName": undefined,
@@ -347,6 +350,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
                   "minItems": undefined,
                   "options": RedocNormalizedOptions {
                     "allowedMdComponents": Object {},
+                    "codeSamplesLanguages": Array [
+                      "json",
+                    ],
                     "disableSearch": false,
                     "downloadDefinitionUrl": undefined,
                     "downloadFileName": undefined,
@@ -605,6 +611,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
             "minItems": undefined,
             "options": RedocNormalizedOptions {
               "allowedMdComponents": Object {},
+              "codeSamplesLanguages": Array [
+                "json",
+              ],
               "disableSearch": false,
               "downloadDefinitionUrl": undefined,
               "downloadFileName": undefined,
@@ -925,6 +934,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
                   "minItems": undefined,
                   "options": RedocNormalizedOptions {
                     "allowedMdComponents": Object {},
+                    "codeSamplesLanguages": Array [
+                      "json",
+                    ],
                     "disableSearch": false,
                     "downloadDefinitionUrl": undefined,
                     "downloadFileName": undefined,
@@ -1208,6 +1220,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
                   "minItems": undefined,
                   "options": RedocNormalizedOptions {
                     "allowedMdComponents": Object {},
+                    "codeSamplesLanguages": Array [
+                      "json",
+                    ],
                     "disableSearch": false,
                     "downloadDefinitionUrl": undefined,
                     "downloadFileName": undefined,
@@ -1462,6 +1477,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
             "minItems": undefined,
             "options": RedocNormalizedOptions {
               "allowedMdComponents": Object {},
+              "codeSamplesLanguages": Array [
+                "json",
+              ],
               "disableSearch": false,
               "downloadDefinitionUrl": undefined,
               "downloadFileName": undefined,
@@ -1741,6 +1759,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
         ],
         "options": RedocNormalizedOptions {
           "allowedMdComponents": Object {},
+          "codeSamplesLanguages": Array [
+            "json",
+          ],
           "disableSearch": false,
           "downloadDefinitionUrl": undefined,
           "downloadFileName": undefined,
@@ -2050,6 +2071,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
             "minItems": undefined,
             "options": RedocNormalizedOptions {
               "allowedMdComponents": Object {},
+              "codeSamplesLanguages": Array [
+                "json",
+              ],
               "disableSearch": false,
               "downloadDefinitionUrl": undefined,
               "downloadFileName": undefined,
@@ -2321,6 +2345,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
             "minItems": undefined,
             "options": RedocNormalizedOptions {
               "allowedMdComponents": Object {},
+              "codeSamplesLanguages": Array [
+                "json",
+              ],
               "disableSearch": false,
               "downloadDefinitionUrl": undefined,
               "downloadFileName": undefined,
@@ -2579,6 +2606,9 @@ exports[`Components SchemaView discriminator should correctly render SchemaView
       "minItems": undefined,
       "options": RedocNormalizedOptions {
         "allowedMdComponents": Object {},
+        "codeSamplesLanguages": Array [
+          "json",
+        ],
         "disableSearch": false,
         "downloadDefinitionUrl": undefined,
         "downloadFileName": undefined,

src/constants/languages.ts

@@ -0,0 +1,4 @@
+export const CODE_SAMPLE_LANGUAGES = {
+  JSON: 'json',
+  XML: 'xml',
+} as const;

src/services/OpenAPIParser.ts

@@ -1,9 +1,10 @@
 import type { OpenAPIRef, OpenAPISchema, OpenAPISpec } from '../types';
-import { IS_BROWSER, getDefinitionName } from '../utils/';
+import { IS_BROWSER, getDefinitionName, compact, isObject, isObjectEmpty } from '../utils/';
 import { JsonPointer } from '../utils/JsonPointer';
 
 import { RedocNormalizedOptions } from './RedocNormalizedOptions';
 import type { MergedOpenAPISchema } from './types';
+import type { OpenAPIExample } from '../types';
 
 const MAX_DEREF_DEPTH = 999; // prevent circular detection crashes by adding hard limit on deref depth
 
@@ -335,6 +336,98 @@ export class OpenAPIParser {
     return receiver;
   }
 
+  derefSchemaWithExample(
+    schema: MergedOpenAPISchema,
+    example: OpenAPIExample & OpenAPISchema,
+  ): OpenAPISchema {
+    const { resolved: resolvedSchema } = this.deref(schema);
+
+    const worker = (
+      currentSchema: MergedOpenAPISchema,
+      currentExample: OpenAPIExample & OpenAPISchema,
+    ) => {
+      const receiver: OpenAPISchema = {
+        ...currentSchema,
+      };
+      if (isObject(currentSchema.properties)) {
+        receiver.properties = Object.fromEntries(
+          Object.entries(currentSchema.properties).map(([key, value]) => {
+            let resolvedValue: OpenAPISchema = {};
+            const exampleForProp = currentExample?.[key];
+
+            if (Array.isArray(value.allOf) && !isObjectEmpty(exampleForProp)) {
+              resolvedValue = this.mergeAllOf(value, undefined, value['x-refsStack'] || []);
+            } else if (Array.isArray(value.oneOf) && !isObjectEmpty(exampleForProp)) {
+              resolvedValue = this.deref(value.oneOf[0]).resolved;
+            } else if (value.$ref) {
+              resolvedValue = this.deref(value).resolved;
+            } else if ((value.items as OpenAPISchema)?.$ref) {
+              resolvedValue = {
+                ...value,
+                items: this.deref(value.items as OpenAPISchema, value.items?.['x-refsStack'] || [])
+                  .resolved,
+              };
+            } else if (Array.isArray(value.items)) {
+              resolvedValue = {
+                ...value,
+                items: value.items.map((item, i) =>
+                  item.properties
+                    ? worker(item, exampleForProp[i])
+                    : this.deref(item, item['x-refsStack'] || []).resolved,
+                ),
+              };
+            } else {
+              resolvedValue = value;
+            }
+
+            if (
+              resolvedValue.properties &&
+              (!isObjectEmpty(exampleForProp) || exampleForProp.length > 0)
+            ) {
+              resolvedValue = worker(resolvedValue, exampleForProp?.[0] ?? exampleForProp);
+            }
+            if ((resolvedValue.items as OpenAPISchema)?.properties && isObject(exampleForProp[0])) {
+              resolvedValue.items = worker(resolvedValue.items as OpenAPISchema, exampleForProp[0]);
+            }
+
+            if (!isObject(exampleForProp)) {
+              resolvedValue = {
+                ...resolvedValue,
+                example: exampleForProp,
+              };
+            }
+
+            const resolved = compact({
+              const: resolvedValue.const,
+              description: resolvedValue.description,
+              deprecated: resolvedValue.deprecated,
+              enum: resolvedValue.enum,
+              example: resolvedValue.example,
+              exclusiveMinimum: resolvedValue.exclusiveMinimum,
+              format: resolvedValue.format,
+              items: resolvedValue.items,
+              maximum: resolvedValue.maximum,
+              maxLength: resolvedValue.maxLength,
+              minimum: resolvedValue.minimum,
+              minLength: resolvedValue.minLength,
+              pattern: resolvedValue.pattern,
+              properties: resolvedValue.properties,
+              readOnly: resolvedValue.readOnly,
+              type: resolvedValue.type,
+              writeOnly: resolvedValue.writeOnly,
+              xml: resolvedValue.xml,
+            });
+
+            return [key, resolved];
+          }),
+        );
+      }
+      return receiver;
+    };
+
+    return worker(resolvedSchema, example);
+  }
+
   /**
    * Find all derived definitions among #/components/schemas from any of $refs
    * returns map of definition pointer to definition name

src/services/RedocNormalizedOptions.ts

@@ -5,6 +5,9 @@ import { isArray, isNumeric, mergeObjects } from '../utils/helpers';
 import { setRedocLabels } from './Labels';
 import { SideNavStyleEnum } from './types';
 import type { LabelsConfigRaw, MDXComponentMeta } from './types';
+import { CODE_SAMPLE_LANGUAGES } from '../constants/languages';
+
+export type CodeSamplesLanguage = typeof CODE_SAMPLE_LANGUAGES[keyof typeof CODE_SAMPLE_LANGUAGES];
 
 export interface RedocRawOptions {
   theme?: ThemeInterface;
@@ -56,6 +59,7 @@ export interface RedocRawOptions {
   hideFab?: boolean;
   minCharacterLengthToInitSearch?: number;
   showWebhookVerb?: boolean;
+  codeSamplesLanguages?: CodeSamplesLanguage[];
 }
 
 export function argValueToBoolean(val?: string | boolean, defaultValue?: boolean): boolean {
@@ -211,6 +215,16 @@ export class RedocNormalizedOptions {
     return 10;
   }
 
+  private static normalizeCodeSamplesLanguages(
+    value?: CodeSamplesLanguage[],
+  ): CodeSamplesLanguage[] {
+    if (isArray(value)) {
+      return value.map(lang => lang.toLowerCase()) as CodeSamplesLanguage[];
+    }
+
+    return [CODE_SAMPLE_LANGUAGES.JSON];
+  }
+
   theme: ResolvedThemeInterface;
   scrollYOffset: () => number;
   hideHostname: boolean;
@@ -258,6 +272,7 @@ export class RedocNormalizedOptions {
   showWebhookVerb: boolean;
 
   nonce?: string;
+  codeSamplesLanguages: CodeSamplesLanguage[];
 
   constructor(raw: RedocRawOptions, defaults: RedocRawOptions = {}) {
     raw = { ...defaults, ...raw };
@@ -335,5 +350,8 @@ export class RedocNormalizedOptions {
     this.hideFab = argValueToBoolean(raw.hideFab);
     this.minCharacterLengthToInitSearch = argValueToNumber(raw.minCharacterLengthToInitSearch) || 3;
     this.showWebhookVerb = argValueToBoolean(raw.showWebhookVerb);
+    this.codeSamplesLanguages = RedocNormalizedOptions.normalizeCodeSamplesLanguages(
+      raw.codeSamplesLanguages,
+    );
   }
 }

src/services/__tests__/OpenAPIParser.test.ts

@@ -72,5 +72,36 @@ describe('Models', () => {
 
       expect(parser.deref(schemaOrRef, [], true)).toMatchSnapshot();
     });
+
+    test('should deref the properties of a schema', () => {
+      const spec = require('./fixtures/properties.json');
+      parser = new OpenAPIParser(spec, undefined, opts);
+      const string = 'string';
+      const example = {
+        id: 0,
+        category: {
+          id: 0,
+          name: string,
+          sub: {
+            prop1: string,
+          },
+        },
+        name: 'Guru',
+        photoUrls: [string],
+        friend: {},
+        tags: [
+          {
+            id: 0,
+            name: string,
+          },
+        ],
+        status: 'available',
+        petType: string,
+      };
+
+      expect(
+        parser.derefSchemaWithExample(spec.components.schemas.test, example),
+      ).toMatchSnapshot();
+    });
   });
 });