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,18 @@ You can use all of the following options with the standalone version of the <red
  * `backgroundColor`: '#263238'
  * `color`: '#ffffff'
 
+## Auto generated code samples
+### Responses
+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','csv']
+```
+
+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', 'csv'],
+};
 
 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,5 @@
+export const CODE_SAMPLE_LANGUAGES = {
+ JSON: 'json',
+ XML: 'xml',
+ CSV: 'csv',
+} 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,105 @@ export class OpenAPIParser {
  return receiver;
  }
 
+ /**
+ * Recursively deref the properties of a schema and attach examples
+ *
+ * @param {MergedOpenAPISchema} schema
+ * @param {OpenAPIExample & OpenAPISchema} example
+ * @returns {OpenAPISchema}
+ */
+ 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();
+ });
  });
 });