Skip to main content

Importing Swagger/OpenAPI

Nidra makes it easy to import complete API definitions from Swagger/OpenAPI specifications, saving you time and ensuring accuracy.

What You'll Learn​

  • How to import Swagger 2.0 and OpenAPI 3.x specifications
  • Managing multiple API versions
  • Updating imported collections when APIs change
  • Best practices for working with imported APIs

Prerequisites​

You'll need:

  • A Swagger/OpenAPI specification file (JSON or YAML)
  • Or a URL to a specification endpoint

Importing from File​

  1. Click "Import" in the toolbar
  2. Select "Swagger/OpenAPI"
  3. Choose "From File"
  4. Browse to your specification file
  5. Configure import options
  6. Click "Import"

Nidra will create a new collection with all endpoints from the specification.

Importing from URL​

Many APIs expose their Swagger spec at a URL (e.g., /swagger.json or /api-docs):

  1. Click "Import"
  2. Select "Swagger/OpenAPI"
  3. Choose "From URL"
  4. Enter the specification URL
  5. Configure import options
  6. Click "Import"

Import Options​

When importing, you can configure:

  • Collection name: Name for the imported collection
  • Generate examples: Create example requests from spec
  • Include deprecated: Import deprecated endpoints
  • Authentication: Pre-configure auth from spec

What Gets Imported​

Nidra imports:

  • All endpoints and operations
  • Request parameters (path, query, header, body)
  • Request body schemas
  • Response examples
  • Authentication requirements
  • Tags and descriptions

After Import​

After importing:

  1. Review the generated collection
  2. Set up environment variables for base URL
  3. Configure authentication if needed
  4. Test the imported requests
  5. Save the collection

Managing Multiple Versions​

Nidra excels at managing multiple API versions simultaneously.

Version Naming Strategy​

Use a consistent naming convention:

  • MyAPI v1
  • MyAPI v2
  • MyAPI v3-beta

Environment Variables​

Create version-specific environments:

EnvironmentbaseUrlversion
v1-prodhttps://api.example.com/v1v1
v2-prodhttps://api.example.com/v2v2

Testing Across Versions​

Test the same workflow across multiple versions:

  1. Create conduits for common workflows
  2. Duplicate the conduit for each version
  3. Switch environments to test different versions
  4. Compare responses and behavior

Learn more about multi-version testing →

Updating Imported Collections​

When your API specification changes:

  1. Re-import the specification
  2. Choose "Update existing collection"
  3. Nidra will merge changes
  4. Review the updated endpoints
  5. Test affected requests

Handling Breaking Changes​

If the API has breaking changes:

  • Review the diff before confirming update
  • Update affected conduits
  • Update environment variables if needed
  • Test thoroughly before deploying

Best Practices​

  • Import regularly: Keep your collections in sync with the API
  • Use version control: Track changes to your collections
  • Document customizations: Note any manual changes to imported requests
  • Test after import: Verify that imported requests work correctly
  • Organize by version: Keep different API versions in separate collections

Troubleshooting​

Import Fails​

If import fails:

  • Verify the specification is valid (use swagger.io validator)
  • Check the file format (JSON vs YAML)
  • Ensure the URL is accessible
  • Review error messages for specific issues

Missing Endpoints​

Incorrect Request Bodies​

Next Steps​