Importing Collections

Import API collections from OpenAPI, WSDL, and other formats into Bruno

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: -o

Conflicts with: --output-file

--output-file · string

Path to export the collection as a JSON file instead of a directory.

Aliases: -f

Conflicts 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: -g

Options:

• 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 [e-mail]
          git add bruno-collection/
          git commit -m "Update Bruno collection from OpenAPI spec" || exit 0
          git push

Post-Import Steps

1. Review the collection - Check that all endpoints were imported correctly
2. Add environments - Create environment files for different stages
3. Add tests - Enhance requests with assertions and tests
4. Configure auth - Set up authentication for your endpoints
5. 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