Importing Collections

The bru import command allows you to convert API specifications from other formats into Bruno collections. This is useful for:

Migrating from other API tools
Generating collections from OpenAPI/Swagger specs
Converting SOAP/WSDL services to Bruno format
Automating collection creation from API documentation

Supported Formats

Bruno CLI currently supports importing from:

OpenAPI - OpenAPI 3.x and Swagger 2.x specifications (JSON/YAML)
WSDL - SOAP Web Service Definition Language

OpenAPI Import

Basic Import

Import an OpenAPI specification from a local file:

bru import openapi --source api.yml --output ~/Desktop/my-collection --collection-name "My API"

Using short aliases:

bru import openapi -s api.yml -o ~/Desktop/my-collection -n "My API"

Import from URL

Import directly from a remote URL:

bru import openapi --source https://api.example.com/openapi.json --output ~/Desktop/remote-api --collection-name "Remote API"

Skip SSL Verification

For URLs with self-signed certificates:

Only use --insecure in development/testing. Never in production.

bru import openapi --source https://self-signed.example.com/api.json --insecure --output ~/Desktop/api

Collection Formats

Specify the output format:

bru import openapi -s api.yml -o ~/Desktop/collection --collection-format bru

Options:

opencollection (default) - Uses YAML format (.yml)
bru - Uses Bruno format (.bru)

Grouping Strategies

Control how requests are organized:

bru import openapi -s api.yml -o ~/Desktop/collection --group-by path

Grouping options:

group-by

string

default:"tags"

tags - Group by OpenAPI tags (default)
path - Group by URL path structure

Example: Tags Grouping

OpenAPI

paths:
  /users:
    get:
      tags: [Users]
  /posts:
    get:
      tags: [Posts]

Results in:

my-collection/
├── Users/
│   └── Get Users.bru
└── Posts/
    └── Get Posts.bru

Example: Path Grouping

OpenAPI

paths:
  /api/v1/users:
    get: ...
  /api/v1/posts:
    get: ...

Results in:

my-collection/
└── api/
    └── v1/
        ├── users/
        │   └── Get Users.bru
        └── posts/
            └── Get Posts.bru

Export as JSON

Instead of creating a collection directory, export as a JSON file:

bru import openapi --source api.yml --output-file ~/Desktop/collection.json --collection-name "My API"

Using aliases:

bru import openapi -s api.yml -f ~/Desktop/collection.json -n "My API"

WSDL Import

Basic WSDL Import

Import a SOAP service from WSDL:

bru import wsdl --source service.wsdl --output ~/Desktop/soap-collection --collection-name "SOAP Service"

Import WSDL from URL

bru import wsdl -s https://example.com/service.wsdl -o ~/Desktop/soap-api -n "Remote SOAP Service"

Import Options Reference

--source

string

required

Path to the source file or URL. Can be a local file path or HTTP(S) URL.Aliases: -s

--output

string

Path to the output directory where the collection will be created.Aliases: -oConflicts with: --output-file

--output-file

string

Path to export the collection as a JSON file instead of a directory.Aliases: -fConflicts with: --output

--collection-name

string

Name for the imported collection. If not specified, uses the name from the specification or filename.Aliases: -n

--collection-format

string

default:"opencollection"

Format of the imported collection.Options:

opencollection - YAML format
bru - Bruno format

--insecure

boolean

default:false

Skip SSL certificate verification when fetching from URLs.

Use only in development/testing environments.

--group-by

string

default:"tags"

How to organize imported requests (OpenAPI only).Aliases: -gOptions:

tags - Group by OpenAPI tags
path - Group by URL path structure

Complete Examples

Import Public API Spec

bru import openapi \
  --source https://petstore3.swagger.io/api/v3/openapi.json \
  --output ~/Desktop/petstore \
  --collection-name "Pet Store API" \
  --group-by tags

Import with Custom Format

bru import openapi \
  -s ./specs/internal-api.yml \
  -o ~/projects/api-tests \
  -n "Internal API" \
  --collection-format bru \
  --group-by path

Import and Export as JSON

bru import openapi \
  --source https://api.example.com/v2/openapi.yaml \
  --output-file ./generated/api.json \
  --collection-name "Example API v2" \
  --insecure

Import WSDL Service

bru import wsdl \
  --source https://www.example.com/services/Calculator.wsdl \
  --output ~/Desktop/calculator-service \
  --collection-name "Calculator SOAP Service"

Output Structure

When importing to a directory (--output), Bruno creates:

my-collection/
├── collection.json (or collection.yml for opencollection)
├── environments/
│   └── (any imported environments)
└── (organized request files)

When exporting to JSON (--output-file), you get a single JSON file containing the entire collection structure.

Automating Imports

You can automate collection generation in your CI/CD pipeline:

.github/workflows/generate-collection.yml

name: Generate Bruno Collection

on:
  push:
    paths:
      - 'openapi.yml'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli
      - name: Generate Collection
        run: |
          bru import openapi \
            --source openapi.yml \
            --output ./bruno-collection \
            --collection-name "Generated API"
      - name: Commit Changes
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add bruno-collection/
          git commit -m "Update Bruno collection from OpenAPI spec" || exit 0
          git push

Post-Import Steps

Review the collection - Check that all endpoints were imported correctly
Add environments - Create environment files for different stages
Add tests - Enhance requests with assertions and tests
Configure auth - Set up authentication for your endpoints
Run tests - Verify the collection works:
```
cd ~/Desktop/my-collection
bru run
```

Troubleshooting

Invalid OpenAPI Spec

If import fails, validate your spec:

# Using swagger-cli
npx @apidevtools/swagger-cli validate openapi.yml

URL Fetch Errors

For SSL errors with trusted sources:

bru import openapi --source https://example.com/api.json --insecure --output ./collection

Empty Collection

If the imported collection is empty:

Verify the spec file is valid
Check that paths are defined in the OpenAPI spec
For WSDL, ensure the service definitions are present

Next Steps

Running Tests

Learn how to run your imported collection

CLI Options

Explore all CLI options and flags

​Importing Collections

​Supported Formats

​OpenAPI Import

​Basic Import

​Import from URL

​Skip SSL Verification

​Collection Formats

​Grouping Strategies

​Example: Tags Grouping

​Example: Path Grouping

​Export as JSON

​WSDL Import

​Basic WSDL Import

​Import WSDL from URL

​Import Options Reference

​Complete Examples

​Import Public API Spec

​Import with Custom Format

​Import and Export as JSON

​Import WSDL Service

​Output Structure

​Automating Imports

​Post-Import Steps

​Troubleshooting

​Invalid OpenAPI Spec

​URL Fetch Errors

​Empty Collection

​Next Steps

Running Tests

CLI Options

Importing Collections

Supported Formats

OpenAPI Import

Basic Import

Import from URL

Skip SSL Verification

Collection Formats

Grouping Strategies

Example: Tags Grouping

Example: Path Grouping

Export as JSON

WSDL Import

Basic WSDL Import

Import WSDL from URL

Import Options Reference

Complete Examples

Import Public API Spec

Import with Custom Format

Import and Export as JSON

Import WSDL Service

Output Structure

Automating Imports

Post-Import Steps

Troubleshooting

Invalid OpenAPI Spec

URL Fetch Errors

Empty Collection

Next Steps