Skip to main content

​
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 [email protected]
          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

Build docs developers (and LLMs) love

Get started for freeTalk to us