OpenAPI to Bruno

Convert an OpenAPI specification into a Bruno collection folder you can open in the app or run with the CLI.

The CLI can do this in one command: bru import openapi --source <openapi.yaml> --output <output-folder>. See bru import. Use the script below when you want to process the collection in your own code.

Convert the specification

Install both packages:

npm install @usebruno/converters @usebruno/filestore

The converter returns a JavaScript object. Bruno needs a collection folder, so the script below converts the input and writes that folder in one go. It writes OpenCollection YAML files by default. Change format to 'bru' for .bru files instead.

The script needs Node.js 18 or later.

1. Read the arguments

Import the converter, the file writers from @usebruno/filestore, and Node’s file helpers. Take the paths from the command line and print a usage line if any are missing. format is 'yml' for OpenCollection YAML or 'bru' for classic .bru files.

import { openApiToBruno } from '@usebruno/converters';
import { stringifyCollection, stringifyFolder, stringifyRequest, stringifyEnvironment } from '@usebruno/filestore';
import { mkdir, readFile, writeFile } from 'fs/promises';
import path from 'path';

const [inputFile, outputDir] = process.argv.slice(2);
if (!inputFile || !outputDir) {
  console.error('Usage: node convert.mjs <openapi.yaml> <output-folder>');
  process.exit(1);
}

const format = 'yml';

2. Add the helpers

safeName strips characters that are not allowed in file names. write saves a file and creates any missing parent folders.

const safeName = (name) => name.replace(/[<>:"/\\|?*\x00-\x1F]/g, '-');

const write = async (file, content) => {
  await mkdir(path.dirname(file), { recursive: true });
  await writeFile(file, content);
};

3. Convert

openApiToBruno accepts the specification as JSON or YAML and returns the Bruno collection. Pass { groupBy: 'path' } as a second argument to group folders by path instead of tag. See the API Reference for the full signature.

const collection = openApiToBruno(await readFile(inputFile, 'utf8'));

4. Write the collection settings and environments

brunoConfig holds the collection settings. For .bru collections it is written to bruno.json. For yml it is embedded in opencollection.yml. The collection root holds collection-level auth, headers, and scripts. Each environment gets its own file in the environments folder.

const brunoConfig = { version: collection.version, name: collection.name, type: 'collection', ignore: ['node_modules', '.git'] };

const root = stringifyCollection(collection.root || {}, brunoConfig, { format });
if (format === 'yml') {
  await write(path.join(outputDir, 'opencollection.yml'), root);
} else {
  await write(path.join(outputDir, 'bruno.json'), JSON.stringify(brunoConfig, null, 2));
  await write(path.join(outputDir, 'collection.bru'), root);
}

for (const env of collection.environments || []) {
  await write(path.join(outputDir, 'environments', `${safeName(env.name)}.${format}`), stringifyEnvironment(env, { format }));
}

5. Write the folders and requests

Each folder becomes a directory and each request a file. Folder-level auth, headers, and scripts go in folder.yml or folder.bru. A stack is used instead of recursion so deeply nested collections are safe.

const stack = collection.items.map((item) => [item, outputDir]);
while (stack.length) {
  const [item, parent] = stack.pop();
  if (item.type === 'folder') {
    const folderDir = path.join(parent, safeName(item.name));
    await mkdir(folderDir, { recursive: true });
    if (item.root) await write(path.join(folderDir, `folder.${format}`), stringifyFolder(item.root, { format }));
    for (const child of item.items || []) stack.push([child, folderDir]);
  } else {
    await write(path.join(parent, `${safeName(item.name)}.${format}`), stringifyRequest(item, { format }));
  }
}

6. Report

Print where the collection was written.

console.log(`Collection written to ${outputDir}`);

7. Run the script

Run the script with Node.js, passing the paths as arguments.

node convert.mjs <openapi.yaml> <output-folder>

node convert.js <openapi.yaml> <output-folder>

Where:

<openapi.yaml>: The OpenAPI specification, as JSON or YAML
<output-folder>: The folder to create the Bruno collection in. It is created if it does not exist

The output folder looks like this (with format set to 'bru', the files are bruno.json, collection.bru, folder.bru, and .bru requests instead):

my-collection/
├── opencollection.yml
├── environments/
│   └── Environment 1.yml
└── pets/
    ├── folder.yml
    ├── List pets.yml
    └── Create pet.yml

One folder per tag, one file per operation, and an environment holding the base URL from the spec’s servers.

Full script

The complete script, ready to copy. convert.mjs is an ES module with top-level await. convert.js is the same script as CommonJS, with the steps inside an async main function.

// Converts an OpenAPI specification into a Bruno collection folder.
// Usage: node convert.mjs <openapi.yaml> <output-folder>

import { openApiToBruno } from '@usebruno/converters';
import { stringifyCollection, stringifyFolder, stringifyRequest, stringifyEnvironment } from '@usebruno/filestore';
import { mkdir, readFile, writeFile } from 'fs/promises';
import path from 'path';

// ---- Arguments ----

const [inputFile, outputDir] = process.argv.slice(2);
if (!inputFile || !outputDir) {
  console.error('Usage: node convert.mjs <openapi.yaml> <output-folder>');
  process.exit(1);
}

// 'yml' (OpenCollection YAML) or 'bru' (classic .bru files)
const format = 'yml';

// ---- Helpers ----

// Strip characters not allowed in file names
const safeName = (name) => name.replace(/[<>:"/\\|?*\x00-\x1F]/g, '-');

// Write a file, creating parent folders as needed
const write = async (file, content) => {
  await mkdir(path.dirname(file), { recursive: true });
  await writeFile(file, content);
};

// ---- Convert ----

// Accepts JSON or YAML. Pass { groupBy: 'path' } as a second argument to group folders by path instead of tag.
const collection = openApiToBruno(await readFile(inputFile, 'utf8'));

// ---- Write the collection folder ----

// Collection settings: bruno.json for .bru, embedded in opencollection.yml for yml
const brunoConfig = { version: collection.version, name: collection.name, type: 'collection', ignore: ['node_modules', '.git'] };

// Collection-level auth, headers, and scripts
const root = stringifyCollection(collection.root || {}, brunoConfig, { format });
if (format === 'yml') {
  await write(path.join(outputDir, 'opencollection.yml'), root);
} else {
  await write(path.join(outputDir, 'bruno.json'), JSON.stringify(brunoConfig, null, 2));
  await write(path.join(outputDir, 'collection.bru'), root);
}

// One file per environment
for (const env of collection.environments || []) {
  await write(path.join(outputDir, 'environments', `${safeName(env.name)}.${format}`), stringifyEnvironment(env, { format }));
}

// Folders become directories, requests become files. A stack avoids recursion on deep trees.
const stack = collection.items.map((item) => [item, outputDir]);
while (stack.length) {
  const [item, parent] = stack.pop();
  if (item.type === 'folder') {
    const folderDir = path.join(parent, safeName(item.name));
    await mkdir(folderDir, { recursive: true });
    // Folder-level auth, headers, and scripts
    if (item.root) await write(path.join(folderDir, `folder.${format}`), stringifyFolder(item.root, { format }));
    for (const child of item.items || []) stack.push([child, folderDir]);
  } else {
    await write(path.join(parent, `${safeName(item.name)}.${format}`), stringifyRequest(item, { format }));
  }
}

// ---- Report ----

console.log(`Collection written to ${outputDir}`);

// Converts an OpenAPI specification into a Bruno collection folder.
// Usage: node convert.js <openapi.yaml> <output-folder>

const { openApiToBruno } = require('@usebruno/converters');
const { stringifyCollection, stringifyFolder, stringifyRequest, stringifyEnvironment } = require('@usebruno/filestore');
const { mkdir, readFile, writeFile } = require('fs/promises');
const path = require('path');

// ---- Arguments ----

const [inputFile, outputDir] = process.argv.slice(2);
if (!inputFile || !outputDir) {
  console.error('Usage: node convert.js <openapi.yaml> <output-folder>');
  process.exit(1);
}

// 'yml' (OpenCollection YAML) or 'bru' (classic .bru files)
const format = 'yml';

// ---- Helpers ----

// Strip characters not allowed in file names
const safeName = (name) => name.replace(/[<>:"/\\|?*\x00-\x1F]/g, '-');

// Write a file, creating parent folders as needed
const write = async (file, content) => {
  await mkdir(path.dirname(file), { recursive: true });
  await writeFile(file, content);
};

// CommonJS cannot use top-level await, so the steps run inside an async function
async function main() {
  // ---- Convert ----

  // Accepts JSON or YAML. Pass { groupBy: 'path' } as a second argument to group folders by path instead of tag.
  const collection = openApiToBruno(await readFile(inputFile, 'utf8'));

  // ---- Write the collection folder ----

  // Collection settings: bruno.json for .bru, embedded in opencollection.yml for yml
  const brunoConfig = { version: collection.version, name: collection.name, type: 'collection', ignore: ['node_modules', '.git'] };

  // Collection-level auth, headers, and scripts
  const root = stringifyCollection(collection.root || {}, brunoConfig, { format });
  if (format === 'yml') {
    await write(path.join(outputDir, 'opencollection.yml'), root);
  } else {
    await write(path.join(outputDir, 'bruno.json'), JSON.stringify(brunoConfig, null, 2));
    await write(path.join(outputDir, 'collection.bru'), root);
  }

  // One file per environment
  for (const env of collection.environments || []) {
    await write(path.join(outputDir, 'environments', `${safeName(env.name)}.${format}`), stringifyEnvironment(env, { format }));
  }

  // Folders become directories, requests become files. A stack avoids recursion on deep trees.
  const stack = collection.items.map((item) => [item, outputDir]);
  while (stack.length) {
    const [item, parent] = stack.pop();
    if (item.type === 'folder') {
      const folderDir = path.join(parent, safeName(item.name));
      await mkdir(folderDir, { recursive: true });
      // Folder-level auth, headers, and scripts
      if (item.root) await write(path.join(folderDir, `folder.${format}`), stringifyFolder(item.root, { format }));
      for (const child of item.items || []) stack.push([child, folderDir]);
    } else {
      await write(path.join(parent, `${safeName(item.name)}.${format}`), stringifyRequest(item, { format }));
    }
  }

  // ---- Report ----

  console.log(`Collection written to ${outputDir}`);
}

main();

Open the collection in the app or run it with the CLI

The spec’s servers become an environment holding the base URL. Select it in the app, or pass its name to --env. Open the folder in the app, or run it with the CLI:

Bruno app
Bruno CLI

Click the + button in the top-left corner and select Import Collection.
Choose Bruno Collection, then browse to the output folder.
Click Import.

See Import Collections for more detail.

cd <output-folder>
bru run

To use an environment, pass its name with --env:

bru run --env <environment-name>

See bru run for more options.

Formats

OpenAPI

OpenCollection YAML

Converters

Bru Lang

Convert the specification

1. Read the arguments

2. Add the helpers

3. Convert

4. Write the collection settings and environments

5. Write the folders and requests

6. Report

7. Run the script

Full script

Open the collection in the app or run it with the CLI

​Convert the specification

​1. Read the arguments

​2. Add the helpers

​3. Convert

​4. Write the collection settings and environments

​5. Write the folders and requests

​6. Report

​7. Run the script

​Full script

​Open the collection in the app or run it with the CLI

Convert the specification

1. Read the arguments

2. Add the helpers

3. Convert

4. Write the collection settings and environments

5. Write the folders and requests

6. Report

7. Run the script

Full script

Open the collection in the app or run it with the CLI