From cdce12501c516bb31eaf19e4d4e930978863e330 Mon Sep 17 00:00:00 2001
From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Date: Wed, 12 Aug 2026 17:36:16 +0200
Subject: [PATCH] generator: support x-omit-from-example on spec properties
 (#915)

A property marked x-omit-from-example: true in the openapi spec is left
out of the composed request/response examples while staying fully
documented in the parameter list and schema blocks. Needed for mutually
exclusive field pairs (policy rule ports vs port_ranges), where
composing an example from every optional field shows a payload the API
rejects. Companion spec change: netbirdio/netbird#7158
---
 generator/api.ts | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/generator/api.ts b/generator/api.ts
index 5f862834..d2c9d0dc 100644
--- a/generator/api.ts
+++ b/generator/api.ts
@@ -203,6 +203,15 @@ async function gen_v3(spec: OpenAPIV3.Document, dest: string) {
   })
 }
 
+// A property marked with `x-omit-from-example: true` in the spec is left out
+// of the composed request/response examples (e.g. one side of a mutually
+// exclusive pair, where including both would show an invalid payload). It
+// remains fully documented in the parameter list, which renders from the
+// schema directly.
+function isOmittedFromExample(schema): boolean {
+  return typeof schema === 'object' && schema !== null && schema['x-omit-from-example'] === true;
+}
+
 function extractInfo(obj, mode = 'example') {
   // Handle the root level object that represents an array
   if (obj.type === 'array' && obj.hasOwnProperty('items')) {
@@ -231,6 +240,9 @@ function extractInfo(obj, mode = 'example') {
       const result = {};
       for (const key in obj.properties) {
         if (obj.properties.hasOwnProperty(key)) {
+          if (mode === 'example' && isOmittedFromExample(obj.properties[key])) {
+            continue;
+          }
           result[key] = extractInfo(obj.properties[key], mode);
         }
       }
@@ -249,10 +261,15 @@ function extractInfo(obj, mode = 'example') {
   }
 
   // Special handling for objects that represent schemas (e.g., with 'type' and 'properties')
+  // Also reached with a bare `properties` map (see the array-items branch above),
+  // so the example omission applies here as well.
   if (typeof obj === 'object' && obj !== null) {
     const result = {};
     for (const key in obj) {
       if (obj.hasOwnProperty(key)) {
+        if (mode === 'example' && isOmittedFromExample(obj[key])) {
+          continue;
+        }
         result[key] = extractInfo(obj[key], mode);
       }
     }