feat: new option payloadSampleIdx

README.md

@@ -246,6 +246,7 @@ You can use all of the following options with standalone version on <redoc> tag
 * `showExtensions` - show vendor extensions ("x-" fields). Extensions used by ReDoc are ignored. Can be boolean or an array of `string` with names of extensions to display.
 * `sortPropsAlphabetically` - sort properties alphabetically.
 * `suppressWarnings` - if set, warnings are not rendered at the top of documentation (they still are logged to the console).
+* `payloadSampleIdx` - if set, payload sample will be inserted at this index or last. Indexes start from 0.
 * `theme` - ReDoc theme. Not documented yet. For details check source code: [theme.ts](https://github.com/Redocly/redoc/blob/master/src/theme.ts).
 * `untrustedSpec` - if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. **Disabled by default** for performance reasons. **Enable this option if you work with untrusted user data!**
 

src/services/RedocNormalizedOptions.ts

@@ -25,6 +25,7 @@ export interface RedocRawOptions {
   menuToggle?: boolean | string;
   jsonSampleExpandLevel?: number | string | 'all';
   hideSchemaTitles?: boolean | string;
+  payloadSampleIdx?: number;
 
   unstable_ignoreMimeParameters?: boolean;
 
@@ -117,6 +118,18 @@ export class RedocNormalizedOptions {
     return value;
   }
 
+  static normalizePayloadSampleIdx(value: RedocRawOptions['payloadSampleIdx']): number {
+    if (typeof value === 'number') {
+      return Math.max(0, value); // always greater or equal than 0
+    }
+
+    if (typeof value === 'string') {
+      return isFinite(value) ? parseInt(value, 10) : 0;
+    }
+
+    return 0;
+  }
+
   private static normalizeJsonSampleExpandLevel(level?: number | string | 'all'): number {
     if (level === 'all') {
       return +Infinity;
@@ -146,6 +159,7 @@ export class RedocNormalizedOptions {
   jsonSampleExpandLevel: number;
   enumSkipQuotes: boolean;
   hideSchemaTitles: boolean;
+  payloadSampleIdx: number;
 
   /* tslint:disable-next-line */
   unstable_ignoreMimeParameters: boolean;
@@ -185,6 +199,7 @@ export class RedocNormalizedOptions {
     );
     this.enumSkipQuotes = argValueToBoolean(raw.enumSkipQuotes);
     this.hideSchemaTitles = argValueToBoolean(raw.hideSchemaTitles);
+    this.payloadSampleIdx = RedocNormalizedOptions.normalizePayloadSampleIdx(raw.payloadSampleIdx);
 
     this.unstable_ignoreMimeParameters = argValueToBoolean(raw.unstable_ignoreMimeParameters);
 

src/services/models/Operation.ts

@@ -108,14 +108,17 @@ export class OperationModel implements IMenuItem {
 
     const requestBodyContent = this.requestBody && this.requestBody.content;
     if (requestBodyContent && requestBodyContent.hasSample) {
+      const insertInx = Math.min(this.codeSamples.length, options.payloadSampleIdx);
+
       this.codeSamples = [
+        ...this.codeSamples.slice(0, insertInx),
         {
           lang: 'payload',
           label: 'Payload',
           source: '',
           requestBodyContent,
         },
-        ...this.codeSamples,
+        ...this.codeSamples.slice(insertInx),
       ];
     }