How to Import OpenAPI and Swagger Files into RESTK: Complete Guide

If you have an OpenAPI or Swagger specification for your API, you are sitting on a goldmine of structured information -- endpoints, parameters, authentication schemes, request bodies, and response examples, all in a single file. Instead of manually creating requests one by one in your API client, you can import the spec and get a fully organized, ready-to-use collection in seconds.

This guide walks through importing OpenAPI 3.x and Swagger 2.0 specifications into RESTK, explains exactly what gets generated during import, and shares best practices for getting the most out of your imported APIs.

What Is OpenAPI / Swagger?

OpenAPI is a specification format for describing REST APIs. It defines a standard, language-agnostic way to document every aspect of an API: its endpoints, request parameters, authentication methods, response schemas, and more. The specification is written in YAML or JSON and can be read by both humans and machines.

Swagger is the original name of the specification. Swagger 2.0 was the last version under the Swagger name before the project was donated to the Linux Foundation and renamed to OpenAPI. OpenAPI 3.0, released in 2017, was the first version under the new name, and OpenAPI 3.1 (released in 2021) brought full JSON Schema compatibility.

In practice, you will encounter both terms used interchangeably. When someone says "Swagger file" or "OpenAPI spec," they are usually referring to the same type of document -- a machine-readable description of an API.

Why Specs Matter for API Testing

A well-maintained OpenAPI specification is the single best starting point for testing an API:

• Every endpoint is documented with its HTTP method, path, and description
• Parameters are typed -- you know exactly what each endpoint expects
• Request body schemas define the shape of POST/PUT payloads
• Authentication requirements are declared at the global and per-endpoint level
• Response schemas tell you what to validate in your test assertions
• Example values give you realistic test data out of the box

Importing this into an API client means you skip the tedious work of manually constructing each request and go straight to testing.

OpenAPI 3.x vs Swagger 2.0

Both formats are supported in RESTK, but there are important differences:

If your API spec is still in Swagger 2.0 format, it will import into RESTK without any issues. That said, if you maintain the spec yourself, migrating to OpenAPI 3.x is worthwhile for the richer feature set. Tools like Swagger Editor can convert Swagger 2.0 to OpenAPI 3.0 automatically.

Importing into RESTK

Step 1: Obtain Your OpenAPI Spec

Before importing, you need the specification file. Here are the most common ways to get it:

From your backend team:

Most modern API frameworks generate OpenAPI specs automatically. Ask your backend team for the spec file or the URL where it is hosted (commonly /api-docs, /swagger.json, or /openapi.yaml).

From a public API:

Many public APIs publish their spec. Check the developer documentation for a download link or a hosted spec URL. For example:

https://api.example.com/v1/openapi.yaml
https://petstore.swagger.io/v2/swagger.json

From code generation tools:

If you are building the API, frameworks like FastAPI (Python), NestJS (TypeScript), Spring Boot (Java), and ASP.NET Core generate OpenAPI specs from your code annotations.

Validate before importing:

It is good practice to validate your spec before importing. An invalid spec may produce incomplete or incorrect results. You can validate using:

• Swagger Editor -- paste your spec and check for errors
• Spectral -- a command-line OpenAPI linter
• The online OpenAPI Validator

Step 2: Import in RESTK

1. Open RESTK
2. Click File > Import in the menu bar (or use the keyboard shortcut Cmd+I)
3. Select OpenAPI 3.x or Swagger 2.0 as the import type, depending on your spec version
4. Choose your .yaml or .json file
5. RESTK displays an import preview showing:
   • The API title and version from the spec
   • Number of endpoints detected
   • Folder structure (based on tags)
   • Authentication schemes found
6. Review the preview and click Import

The entire collection is generated instantly. You will see it appear in your sidebar, organized and ready to use.

Step 3: What Gets Generated

When you import an OpenAPI spec, RESTK creates a complete, organized collection. Here is exactly what maps from the spec to your workspace.

Endpoints Become Requests

Every path and method combination in the spec becomes a request in RESTK:

# OpenAPI spec
paths:
  /users:
    get:
      summary: List all users
      tags: [Users]
    post:
      summary: Create a user
      tags: [Users]
  /users/{id}:
    get:
      summary: Get user by ID
      tags: [Users]
    put:
      summary: Update a user
      tags: [Users]
    delete:
      summary: Delete a user
      tags: [Users]

This generates five requests in RESTK: "List all users" (GET), "Create a user" (POST), "Get user by ID" (GET), "Update a user" (PUT), and "Delete a user" (DELETE) -- all with the correct HTTP methods and URLs pre-configured.

Tags Become Folders

OpenAPI tags are used to organize endpoints into logical groups. RESTK maps these to folders:

tags:
  - name: Users
    description: User management endpoints
  - name: Orders
    description: Order processing endpoints
  - name: Products
    description: Product catalog endpoints

This creates three folders in your collection: Users, Orders, and Products. Each request is placed in the folder matching its tag.

Parameters Are Pre-Filled

Path parameters, query parameters, and headers defined in the spec are automatically configured:

/users/{id}:
  get:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: "usr_123"
      - name: include
        in: query
        schema:
          type: string
          enum: [profile, orders, preferences]
        example: "profile"

RESTK creates the request with {{id}} as a path variable (pre-filled with the example value usr_123 if provided) and include as a query parameter with the example value profile.

Request Bodies Are Generated

For POST, PUT, and PATCH endpoints, RESTK generates request bodies from the schema:

/users:
  post:
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [name, email]
            properties:
              name:
                type: string
                example: "Jane Doe"
              email:
                type: string
                format: email
                example: "[email protected]"
              role:
                type: string
                enum: [admin, member, viewer]
                example: "member"

The generated request in RESTK includes a JSON body pre-filled with:

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "role": "member"
}

If no example values are provided in the spec, RESTK generates placeholder values based on the schema types (empty strings for string, 0 for integer, false for boolean).

Authentication Schemes Are Configured

OpenAPI security schemes map to authentication settings in RESTK:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access

RESTK configures the collection's authentication settings to match. If the spec declares security: [BearerAuth: []] at the top level, the collection is set to use Bearer Token authentication. Individual endpoints that override the global security setting are configured independently.

Server URLs Map to Environments

If the spec defines multiple servers, RESTK can use these to set up your base URLs:

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:3000/v1
    description: Local development

The first server URL is used as the base URL for the generated requests. You can then create environments in RESTK for each server and switch between them:

• Production environment: base_url = https://api.example.com/v1
• Staging environment: base_url = https://staging-api.example.com/v1
• Local environment: base_url = http://localhost:3000/v1

Working with Imported APIs

Once the import is complete, here is how to get productive quickly.

Setting Up Environment Variables

The imported collection uses the server URL directly. To make it flexible across environments:

1. Go to Environments in RESTK
2. Create environments for each context (Development, Staging, Production)
3. Add a base_url variable in each environment with the appropriate server URL
4. Update the imported requests to use {{base_url}} instead of the hardcoded server URL

This lets you switch between environments with a single click, without modifying any requests.

Configuring Authentication

After import, you need to provide actual credentials:

1. If the spec uses Bearer Token auth, create an environment variable called access_token and set its value to your actual token
2. If the spec uses API Key auth, add the key value to your environment variables
3. If the spec uses Basic Auth, configure the username and password in RESTK's auth settings

You can also write a pre-request script at the collection level to handle authentication automatically. See our Nova scripting guide for examples.

Running Your First Test

With the collection imported and authentication configured:

1. Select any GET endpoint (these are usually the simplest to verify)
2. Make sure your environment is active and variables are set
3. Click Send
4. Verify the response -- you should see a valid JSON response with the expected structure

Once the basic requests work, add post-request scripts to automate validation:

nova.test("Status is 200", function() {
  nova.expect(nova.response.status).toBe(200);
});

nova.test("Response matches expected schema", function() {
  const data = nova.response.json();
  nova.expect(data).toHaveProperty("id");
  nova.expect(data).toHaveProperty("name");
});

Tips for Better Imports

The quality of your import depends entirely on the quality of your OpenAPI spec. Here are practical tips for getting the best results.

Keep Your Spec Well-Documented

Descriptions in your spec become descriptions in RESTK. A well-documented spec means you do not need to guess what each endpoint does:

# Good: descriptive
/users/{id}/orders:
  get:
    summary: List orders for a user
    description: >
      Returns a paginated list of orders placed by the specified user.
      Results are sorted by creation date in descending order.
      Requires authentication with read scope.

# Less useful: minimal
/users/{id}/orders:
  get:
    summary: Get orders

Use Proper Examples

Example values are the difference between an import that is ready to test immediately and one that requires manual data entry for every request:

# Good: realistic examples
properties:
  name:
    type: string
    example: "Jane Doe"
  email:
    type: string
    example: "[email protected]"
  age:
    type: integer
    example: 32

# Less useful: no examples
properties:
  name:
    type: string
  email:
    type: string
  age:
    type: integer

With examples, RESTK pre-fills request bodies so you can send the request immediately.

Validate Your Spec Before Importing

A spec with syntax errors or missing references will produce an incomplete import. Before importing into RESTK:

1. Open Swagger Editor and paste your spec
2. Fix any errors or warnings shown in the validation panel
3. Pay particular attention to $ref references -- broken references are the most common issue
4. Verify that all required fields are present

Use Tags Consistently

Tags control how endpoints are organized into folders. Use them consistently for a clean collection structure:

# Good: consistent, meaningful tags
paths:
  /users:
    get:
      tags: [Users]
  /users/{id}:
    get:
      tags: [Users]
  /orders:
    get:
      tags: [Orders]

# Problematic: inconsistent tags
paths:
  /users:
    get:
      tags: [User Management]
  /users/{id}:
    get:
      tags: [Users]  # Different tag name = different folder

Include Security Schemes

If your API requires authentication, define it in the spec so RESTK can configure it automatically:

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Without this, you will need to manually configure authentication on every imported request.

Other Supported Import Formats

OpenAPI and Swagger are not the only formats RESTK supports. Here is a summary of all import options:

If you are migrating from Postman specifically, our detailed Postman migration guide covers the process step by step, including script conversion, environment migration, and team rollout planning. You can also visit the Migrate from Postman page for a feature-by-feature comparison.

Keeping Specs in Sync

APIs evolve, and your OpenAPI spec will change over time as endpoints are added, parameters are modified, and schemas are updated. Here are strategies for keeping your RESTK collection in sync:

• Re-import periodically. When the spec changes significantly, import it again into a new collection. Compare with your existing collection and merge the changes.
• Use version control. If your spec is in a Git repository, you can track changes over time and re-import when you notice relevant updates.
• Subscribe to spec changes. Some API platforms notify consumers when the spec is updated. Use these notifications as a trigger to re-import.

Full Documentation

This guide covers the most common import workflow. For complete documentation on all import options, error handling, offline imports, and troubleshooting, visit the Import documentation. If you are migrating from Postman, our Migrate from Postman page has a step-by-step walkthrough.

Conclusion

Importing an OpenAPI or Swagger specification into RESTK is the fastest way to go from "I have access to an API" to "I have a complete, organized, testable collection." Instead of spending time manually creating requests, you start with a fully structured workspace and can immediately focus on what matters: testing behavior, validating responses, and building automation.

If your API has a spec, use it. If it does not, consider generating one -- the upfront investment pays for itself many times over, not just for import but for documentation, code generation, and team onboarding.

Download RESTK and import your first OpenAPI spec in under a minute.

---

Related reading:

• How to Import Postman Collections into RESTK
• API Automation with Nova Scripts: A Complete Guide

Having trouble with an import? Join our Discord community or email [email protected] with your spec file and we will help you sort it out.