Preecha

Posted on May 7

API Testing Tools That Support OpenAPI 3.1

#api #automation #testing #tooling

OpenAPI 3.1 is becoming the standard for API specifications because it aligns with JSON Schema 2020-12, improves interoperability, and gives teams more accurate validation. If you are migrating from OpenAPI 3.0.x—or starting a new API—you need testing tools that can import OpenAPI 3.1 specs, validate schemas correctly, and fit into your development workflow.

Try Apidog today

This guide compares API testing tools that support OpenAPI 3.1 and shows how to use them in practical workflows: importing specs, generating tests, validating schemas, mocking APIs, and running checks in CI/CD.

Why OpenAPI 3.1 Support Matters in API Testing

OpenAPI 3.1 introduced important changes over OpenAPI 3.0.x:

Full JSON Schema 2020-12 alignment
Better support for advanced schema validation
Expanded data modeling capabilities
Simplified $ref handling for modular specs
Improved compatibility with JSON Schema tooling

For API testing, this matters because you can:

Validate request and response bodies more accurately
Use advanced schema constraints without workarounds
Generate better test cases from the API contract
Reduce drift between design, docs, mocks, and tests

The key requirement: your testing tool must actually support OpenAPI 3.1 and JSON Schema 2020-12. Some tools can import a 3.1 file but do not fully validate 3.1-specific schema features.

At-a-Glance: OpenAPI 3.1 Support Matrix

Tool	OpenAPI 3.1 Import	Schema Validation	Automated Test Generation	CI/CD Integration	Mock Server	Open Source	Notable Limitations
Apidog	✔️	✔️	✔️	✔️	✔️	❌	No specific limits
Schemathesis	✔️	✔️	✔️	✔️	❌	✔️	CLI only
Hoppscotch	✔️	✔️ Basic	❌	✔️	✔️	✔️	Lacks advanced tests
Insomnia	✔️	✔️	❌	✔️	Partial	✔️	Lacks advanced tests
Stoplight	✔️	✔️	✔️	✔️	✔️	❌	Paid for full suite
Postman	Partial	❌	❌	✔️	✔️	❌	OpenAPI 3.1 support limited
Prism	✔️	✔️	❌	✔️	✔️	✔️	Mocking only

Note: “Partial” means limited feature support. “CLI only” means there is no GUI-based workflow.

1. Apidog

Best for: teams that want API design, testing, mocking, and documentation in one OpenAPI 3.1 workflow.

Apidog provides a spec-driven API platform where teams can design APIs, import/export OpenAPI 3.1 specs, generate tests, validate schemas, create mocks, and maintain documentation from the same source of truth.

Key Features

Import and export OpenAPI 3.1 specs
Generate test cases from API definitions
Validate request and response schemas
Support OpenAPI 3.1 JSON Schema features
Create mock servers for isolated testing
Run scenario-based test suites
Integrate API validation into CI/CD workflows
Support performance testing workflows

Hands-On: Test OpenAPI 3.1 APIs in Apidog

1. Import your OpenAPI 3.1 spec

In Apidog:

Go to Settings
Select Import Data
Choose OpenAPI/Swagger
Upload your OpenAPI 3.1 YAML or JSON file

2. Generate test cases

After importing the spec:

Open the Tests tab
Select an endpoint
Click Generate with AI
Review the generated scenarios for paths, parameters, request bodies, and response schemas

3. Run and validate

Run the generated test suite to validate:

Status codes
Response bodies
Schema conformance
Required fields
Data types
Error responses
Scenario coverage

You can run tests manually during development or include them in your CI workflow.

2. Schemathesis

Best for: automated property-based API testing from OpenAPI 3.1 specs.

Schemathesis is an open-source CLI tool that reads OpenAPI documents and generates test cases automatically. It is useful for finding edge cases, negative cases, and schema violations that manual tests may miss.

Key Features

OpenAPI 3.1 parsing
JSON Schema 2020-12 support
Automated test generation
Negative and edge-case testing
Fuzzing-style API testing
pytest integration
CI/CD-friendly CLI usage
Open source

Walkthrough: Testing an OpenAPI 3.1 Spec with Schemathesis

Install Schemathesis:

pip install schemathesis

Run tests against a deployed API:

schemathesis run openapi.yaml --base-url=https://api.example.com

Example GitHub Actions step:

- name: Run Schemathesis OpenAPI 3.1 tests
  run: schemathesis run openapi.yaml --base-url=https://staging.example.com

Limitation

Schemathesis is CLI-based. It is powerful for automation but does not provide a GUI workflow for manual API exploration.

3. Hoppscotch

Best for: lightweight browser-based API testing with basic OpenAPI 3.1 support.

Hoppscotch is a free, open-source API client. It can import OpenAPI 3.1 documents and generate requests for manual testing. It works well for quick checks, collaboration, and lightweight API exploration.

Key Features

Import OpenAPI 3.1 documents
Auto-populate requests from imported specs
Run manual API requests
Use schema-aware request forms
Mock server capabilities
Web-based workflow
Open source

Quickstart: OpenAPI 3.1 in Hoppscotch

Open the Hoppscotch web app
Click Import
Select OpenAPI 3.1
Import your YAML or JSON spec
Use the generated requests for manual testing

Limitation

Hoppscotch does not provide advanced automated test generation or scenario-based testing. It is best for quick manual checks.

4. Insomnia

Best for: developers who want an extensible API client with OpenAPI 3.1 import and schema-aware testing.

Insomnia supports importing OpenAPI 3.1 specs into request collections. You can organize endpoints, configure environments, run requests, and validate responses.

Key Features

OpenAPI 3.1 import and export
Request collections generated from API specs
Schema-aware requests and validation
Environment variables
Plugin ecosystem
Open-source option

Getting Started: OpenAPI 3.1 in Insomnia

Open Insomnia
Select Create
Choose New Request Collection
Import your OpenAPI 3.1 YAML or JSON file
Run generated requests
Review schema-based validation in the response pane

Limitation

Insomnia is mainly focused on manual and collection-based API testing. It does not provide advanced automated test case generation from OpenAPI 3.1 specs.

5. Stoplight

Best for: teams that need API design, mocking, and testing with OpenAPI 3.1 support.

Stoplight provides a visual API design and testing platform. It supports OpenAPI 3.1 workflows, including validation, mock servers, and test scenarios.

Key Features

Visual API design
OpenAPI 3.1 import and export
Spec validation
Mock server support
Example response generation
Scenario-based testing
CI integration through Stoplight CLI

Example: Validate an OpenAPI 3.1 Spec in Stoplight

Import your OpenAPI 3.1 file into Stoplight Studio
Open the Testing workflow
Generate and run test scenarios
Review validation errors
Check coverage and suggested fixes

Limitation

Some advanced features require paid plans. The open-source offering is more limited.

6. Postman

Best for: teams already using Postman, with caution around OpenAPI 3.1 limitations.

Postman is widely used for API testing, collaboration, monitoring, and mock servers. However, OpenAPI 3.1 support is still limited compared with tools designed around full 3.1 and JSON Schema 2020-12 compatibility.

Key Features

OpenAPI 3.1 import with caveats
Manual request testing
Test scripting
Monitoring
Mock servers
CI integrations

Known Limitations

Some OpenAPI 3.1 and JSON Schema 2020-12 features may not be fully validated
Advanced schema constructs can be missed
Test automation often requires manually written scripts
Imported 3.1 specs may not behave the same as fully supported 3.0.x specs

Practical Recommendation

If your team already uses Postman, you can continue using it for manual API workflows. For full OpenAPI 3.1 validation, pair it with a tool like Schemathesis or Apidog.

7. Prism

Best for: mocking APIs from OpenAPI 3.1 specs.

Prism is an open-source CLI tool from Stoplight for mocking and validating HTTP APIs from OpenAPI documents. It is not a full test runner, but it is useful for contract-based mocking and request/response validation.

Key Features

OpenAPI 3.1 spec parsing
Mock server generation
Example response simulation
Request and response validation
CLI support
Docker-friendly usage
Open source

Quickstart Example

Install Prism:

npm install -g @stoplight/prism-cli

Start a mock server from your OpenAPI spec:

prism mock openapi.yaml

You can then point frontend apps, integration tests, or local clients to the mock server while backend implementation is still in progress.

Real-World Workflow: Migrating to OpenAPI 3.1 in CI/CD

Suppose your team is upgrading API specs from OpenAPI 3.0.x to OpenAPI 3.1. A practical workflow looks like this:

Update your OpenAPI spec to 3.1
Validate schema compatibility
Generate regression tests for existing and new endpoints
Mock incomplete endpoints for frontend development
Run automated checks in CI/CD

Recommended Toolchain

1. Design and validate the spec

Use Apidog or Stoplight to visually inspect and validate your OpenAPI 3.1 document.

Focus on:

$ref correctness
Request body schemas
Response schemas
Required properties
Nullable handling
Advanced JSON Schema constraints

2. Generate API tests

Import the OpenAPI 3.1 spec into Apidog and generate tests from endpoints and schemas.

Use these tests to validate:

Happy paths
Required parameters
Request body constraints
Response schema compliance
Error response behavior

3. Add property-based tests in CI

Use Schemathesis for automated test generation in your pipeline:

# .github/workflows/api-tests.yml
name: API Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  schemathesis:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Schemathesis
        run: pip install schemathesis

      - name: Run Schemathesis OpenAPI 3.1 tests
        run: schemathesis run openapi.yaml --base-url=https://staging.example.com

4. Mock APIs during development

Use Apidog or Prism to create a mock server from the OpenAPI 3.1 spec.

This helps frontend and integration teams work before backend endpoints are fully implemented.

Result

This workflow gives your team:

Faster feedback on schema changes
Better coverage for OpenAPI 3.1 features
Less manual regression testing
More reliable contract validation
Consistent mocks across development and testing

Troubleshooting OpenAPI 3.1 Testing Issues

Spec import failures

Some tools may silently ignore unsupported OpenAPI 3.1 features or downgrade behavior internally.

What to check:

Import warnings
Unsupported keyword messages
Schema validation logs
Broken $ref references
Generated collection differences

Incomplete JSON Schema validation

Tools without full JSON Schema 2020-12 support may miss validation errors.

Examples of features to verify:

if / then / else
unevaluatedProperties
prefixItems
Advanced oneOf, anyOf, and allOf usage
Nullable handling through JSON Schema types
Format validation behavior

CI/CD integration gaps

CLI tools like Schemathesis and Prism are usually easier to automate. GUI-first tools may require APIs, CLIs, plugins, or custom scripts.

For CI/CD, confirm:

Exit codes fail correctly on validation errors
Reports can be exported
Test environments can be configured
Secrets can be passed securely
Base URLs are environment-specific

Fuzzing limitations

Only some tools generate negative, edge-case, or property-based tests directly from the OpenAPI 3.1 contract.

If you need broad automated coverage, include Schemathesis in your pipeline.

Choosing the Right OpenAPI 3.1 Testing Tool

Use this decision guide:

Choose Apidog if you want an all-in-one workflow for OpenAPI 3.1 design, testing, mocking, and documentation.
Choose Schemathesis if you need automated property-based testing in CI/CD.
Choose Hoppscotch if you want lightweight browser-based manual testing.
Choose Insomnia if you want an extensible API client with OpenAPI import support.
Choose Stoplight if your team needs visual API design plus testing and mocking.
Choose Postman if your team already depends on Postman, but validate OpenAPI 3.1 limitations carefully.
Choose Prism if your main requirement is contract-based mocking.

For many teams, the best setup is a combination:

Visual workflow: Apidog or Stoplight
Automated property-based testing: Schemathesis
Mocking: Apidog or Prism
Manual exploration: Hoppscotch, Insomnia, or Postman

Conclusion

OpenAPI 3.1 improves API validation by aligning with JSON Schema 2020-12, but your testing workflow only benefits if your tools support the spec correctly.

For implementation-focused teams:

Use Apidog or Stoplight for visual OpenAPI 3.1 workflows
Use Schemathesis for automated CI/CD testing
Use Prism for contract-based mocks
Use Hoppscotch or Insomnia for quick manual testing
Treat Postman OpenAPI 3.1 support as partial and verify behavior with real specs

Before standardizing on any tool, test it against your actual OpenAPI 3.1 documents—especially if you use advanced JSON Schema features.

Frequently Asked Questions

Q: Can I use OpenAPI 3.1 features in all API testing tools?

No. Some tools only support OpenAPI 3.0.x, and some tools that import OpenAPI 3.1 do not fully validate JSON Schema 2020-12 features.

Q: Which open-source tools support OpenAPI 3.1 testing?

Schemathesis, Hoppscotch, Insomnia, and Prism are open-source options with different strengths. Schemathesis is strongest for automated testing, while Prism is focused on mocking.

Q: How do I automate OpenAPI 3.1 tests in CI/CD?

Use CLI-friendly tools such as Schemathesis. You can run tests from your OpenAPI spec and fail the build when validation or contract checks fail.

Example:

schemathesis run openapi.yaml --base-url=https://staging.example.com

Q: What should I verify before adopting an OpenAPI 3.1 testing tool?

Test the tool with your real API spec and check:

OpenAPI 3.1 import behavior
JSON Schema 2020-12 validation
$ref resolution
Request and response validation
Mock server accuracy
CI/CD support
Reporting and failure behavior