OpenCollection vs OpenAPI
Not competing. Complementing.
Two specifications that work better together.
OpenAPI
Defines what your API is — the contract, the schema, the structure.
- ✓ API endpoints and HTTP methods
- ✓ Request and response schemas
- ✓ Authentication requirements
- ✓ Data types and validation rules
- ✓ API documentation generation
OpenCollection
Defines how to use your API — the scenarios, the workflows, the execution.
- ✓ Business workflows and sequences
- ✓ Pre-request scripts and tests
- ✓ Environment variables and secrets
- ✓ Runnable, shareable collections
- ✓ Living, executable documentation
OpenAPI tells you the shape of the door.
OpenCollection shows you how to walk through it.
Different purposes, same goal
OpenAPI is fantastic for defining your API's contract. It answers questions like: "What endpoints exist?", "What parameters do they accept?", "What does the response look like?" It's the blueprint of your API.
OpenCollection picks up where OpenAPI leaves off. It answers: "How do I authenticate and then fetch user data?", "What's the sequence of calls to complete a checkout?", "How do I test this workflow in CI/CD?" It's the instruction manual — and it's also documentation that you can actually run.
Runnable Docs
While OpenAPI provides living documentation that describes your API structure, collections take it a step further by giving developers real, runnable examples they can import and use immediately.
Better together
Think of building furniture. OpenAPI is the parts list and dimensions. OpenCollection is the step-by-step assembly guide with helpful tips. You need both for the complete picture.
Use OpenAPI when you need to...
- • Generate API documentation
- • Validate request/response payloads
- • Generate client SDKs
- • Define the API contract
Use OpenCollection when you need to...
- • Share runnable API examples
- • Create living, executable docs
- • Test business workflows
- • Automate API testing in CI/CD
- • Onboard developers quickly