Add default option to always show required properties first

Author: pschutz93

packages/compiler/src/content/chunks/operation.ts

@@ -167,7 +167,21 @@ export function renderParameters(
     return;
   }
   debug(`Rendering parameters`);
-  const { showDebugPlaceholders } = getSettings().display;
+  const { showDebugPlaceholders, sortRequiredProperties } =
+    getSettings().display;
+  if (sortRequiredProperties) {
+    debug("Sorting required parameters to top.");
+    parameters.sort((a, b) => {
+      if (a.required && !b.required) {
+        return -1;
+      }
+      if (!a.required && b.required) {
+        return 1;
+      }
+      return a.name.localeCompare(b.name);
+    });
+  }
+
   renderer.createParametersSection(() => {
     for (const parameter of parameters) {
       debug(`Rendering parameter: name=${parameter.name}`);

packages/compiler/src/content/chunks/schema.ts

@@ -4,6 +4,7 @@ import type {
   PropertyAnnotations,
 } from "@speakeasy-api/docs-md-shared";
 
+import { debug } from "../../logging.ts";
 import type { Renderer } from "../../renderers/base.ts";
 import { getSettings } from "../../settings.ts";
 import { assertNever } from "../../util/assertNever.ts";
@@ -518,6 +519,21 @@ export function renderObjectProperties({
       };
     }
   );
+
+  const { sortRequiredProperties } = getSettings().display;
+  if (sortRequiredProperties) {
+    debug("Sorting required parameters to top.");
+    properties.sort((a, b) => {
+      if (a.isRequired && !b.isRequired) {
+        return -1;
+      }
+      if (!a.isRequired && b.isRequired) {
+        return 1;
+      }
+      return a.name.localeCompare(b.name);
+    });
+  }
+
   for (const property of properties) {
     createExpandableProperty({
       renderer,

packages/compiler/src/settings.ts

@@ -375,11 +375,20 @@ export const settingsSchema = z.strictObject({
        * When this setting is enabled, you must also set `output.embedOutDir`
        */
       maxNestingLevel: z.number().optional(),
+
+      /***
+       * Whether or not to sort required properties and parameters first.
+       *
+       * When enabled, properties will still be sorted alphabetically but required
+       * properties will be shown first.
+       */
+      sortRequiredProperties: z.boolean().default(true),
     })
     .default({
       visibleResponses: "explicit",
       showDebugPlaceholders: false,
       expandTopLevelPropertiesOnPageLoad: true,
+      sortRequiredProperties: true,
     }),
 
   /**