Overlay - Support "extends" for referencing OpenAPI documents (#178)

* Overlay - Support "extends" for referencing OpenAPI documents

Author: thim81

CHANGELOG.md

@@ -1,7 +1,8 @@
 ## unreleased
 
+- Overlay: Support "extends" for referencing OpenAPI documents (#176)
 - Improvement: Added safe checks for invalid YAML
-- CLI - Fix relative path generation in $ref when splitting document (#175)
+- CLI: Fix relative path generation in $ref when splitting document (#175)
 
 ## [1.27.3] - 2025-07-30
 

bin/cli.js

@@ -13,7 +13,7 @@ function increaseVerbosity(dummyValue, previous) {
 }
 
 program
-  .arguments('<oaFile>')
+  .arguments('[oaFile]')
   .usage('<file> [options]')
   .description('Format an OpenAPI document by ordering, formatting and filtering fields.')
   .option('-o, --output <output>', 'save the formatted OpenAPI file as JSON/YAML')
@@ -59,11 +59,6 @@ async function run(oaFile, options) {
   let cliLog = {};
   const consoleLine = process.stdout.columns ? '='.repeat(process.stdout.columns) : '='.repeat(80);
 
-  if (!oaFile) {
-    console.error('Please provide a file path for the OpenAPI document');
-    return;
-  }
-
   infoOut(`${consoleLine}`); // LOG - horizontal rule
   infoOut(`OpenAPI-Format CLI settings:`); // LOG - config file
 
@@ -216,24 +211,72 @@ async function run(oaFile, options) {
     }
   }
 
+  // Allow missing input file if overlay extends is provided
+  if (!oaFile) {
+    const hasOverlay = !!options?.overlaySet;
+    const extendsRef = options?.overlaySet?.extends;
+    if (extendsRef) {
+      // Resolve local relative paths against the overlay file location
+      const isRemote =
+        typeof extendsRef === 'string' && (extendsRef.startsWith('http://') || extendsRef.startsWith('https://'));
+      if (isRemote) {
+        oaFile = extendsRef;
+      } else {
+        const baseDir = options?.overlayFile ? path.dirname(path.resolve(options.overlayFile)) : process.cwd();
+        oaFile = path.isAbsolute(extendsRef) ? extendsRef : path.resolve(baseDir, extendsRef);
+      }
+      infoOut(`- Input file (extends):\t${oaFile}`);
+    } else {
+      if (!hasOverlay) {
+        console.error('Please provide a file path for the OpenAPI document');
+      } else {
+        console.error('Please provide an input file or an overlay with an "extends" property');
+      }
+      return;
+    }
+  }
+
   let resObj = {};
   let output = {};
   let input = {};
   let fileOptions = {keepComments: options.keepComments ?? false, bundle: options.bundle ?? true};
 
   try {
-    infoOut(`- Input file:\t\t${oaFile}`); // LOG - Input file
+    if (!options?.overlaySet?.extends) {
+      infoOut(`- Input file:\t\t${oaFile}`); // LOG - Input file (standard)
+    }
 
     // Parse input content
     resObj = await openapiFormat.parseFile(oaFile, fileOptions);
     input = resObj;
   } catch (err) {
-    if (err.code !== 'ENOENT') {
-      console.error('\x1b[31m', `Input file error - Failed to read file: ${err.message}`);
+    // If input file missing but overlay extends is present, fallback to extends
+    const extendsRef = options?.overlaySet?.extends;
+    if (err.code === 'ENOENT' && extendsRef) {
+      const isRemote =
+        typeof extendsRef === 'string' && (extendsRef.startsWith('http://') || extendsRef.startsWith('https://'));
+      if (isRemote) {
+        oaFile = extendsRef;
+      } else {
+        const baseDir = options?.overlayFile ? path.dirname(path.resolve(options.overlayFile)) : process.cwd();
+        oaFile = path.isAbsolute(extendsRef) ? extendsRef : path.resolve(baseDir, extendsRef);
+      }
+      infoOut(`- Input file (extends):\t${oaFile}`);
+      try {
+        resObj = await openapiFormat.parseFile(oaFile, fileOptions);
+        input = resObj;
+      } catch (err2) {
+        console.error('\x1b[31m', `Input file error - Failed to read file: ${err2.message}`);
+        process.exit(1);
+      }
+    } else {
+      if (err.code !== 'ENOENT') {
+        console.error('\x1b[31m', `Input file error - Failed to read file: ${err.message}`);
+        process.exit(1);
+      }
+      console.error('\x1b[31m', `Input file error - Failed to read file: ${oaFile}`);
       process.exit(1);
     }
-    console.error('\x1b[31m', `Input file error - Failed to read file: ${oaFile}`);
-    process.exit(1);
   }
 
   // Generate elements for OpenAPI document

readme.md

@@ -1217,6 +1217,27 @@ example:
 $ openapi-format openapi.yaml --overlayFile overlay.yaml -o openapi-updated.yaml
 ```
 
+You can also let the overlay declare the base OpenAPI document using the top-level `extends` property. When `extends` is present, the input file argument becomes optional:
+
+```yaml
+overlay: 1.0.0
+info:
+  title: Overlay for Tic Tac Toe
+  version: 1.0.0
+extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
+# actions: [...]  # optional
+```
+
+CLI usage with `extends` (no input file argument):
+
+```shell
+$ openapi-format --overlayFile overlay.yaml -o openapi-updated.yaml
+```
+
+Notes:
+- `extends` supports both local paths and remote `http(s)` URLs.
+- Local relative paths are resolved relative to the overlay file’s location.
+
 ## CLI generate usage
 
 - Generate OpenAPI elements and saves it as a new file

test/overlay-extends-local/base.yaml

@@ -0,0 +1,6 @@
+openapi: 3.1.0
+info:
+  title: Base Local
+  version: 1.0.0
+paths: {}
+

test/overlay-extends-local/options.yaml

@@ -0,0 +1,4 @@
+overlayFile: overlay.yaml
+output: output.yaml
+no-sort: true
+

test/overlay-extends-local/output.yaml

@@ -0,0 +1,6 @@
+openapi: 3.1.0
+info:
+  title: Base Local
+  version: 1.0.0
+paths: {}
+

test/overlay-extends-local/overlay.yaml

@@ -0,0 +1,6 @@
+overlay: 1.0.0
+info:
+  title: Local Extends Overlay
+  version: 1.0.0
+extends: './base.yaml'
+

test/overlay-extends-remote/options.yaml

@@ -0,0 +1,4 @@
+overlayFile: overlay.yaml
+output: output.yaml
+no-sort: true
+

test/overlay-extends-remote/output.yaml

@@ -0,0 +1,8 @@
+openapi: 3.0.2
+info:
+  title: Original API
+  version: 1.0.0
+servers:
+  - url: 'https://api.example.com'
+    description: Default server
+    

test/overlay-extends-remote/overlay.yaml

@@ -0,0 +1,5 @@
+overlay: 1.0.0
+info:
+  title: Remote Extends Overlay
+  version: 1.0.0
+extends: 'https://raw.githubusercontent.com/thim81/openapi-format/main/test/overlay-combi/input.yaml'