Specmatic supports OpenAPI 3.0.x
At the time of writing, OpenAPI 3.1.x is new, and many tools are still catching up. The library we use — swagger-parser — currently does not support it either. We will add support as soon as possible.
Here is an exercise to get you started with both Specmatic and how to leverage OpenAPI Support in Specmatic - Getting Started with OpenAPI
You can skip this and go to below sections if you are already acquainted with both OpenAPI and Specmatic.
Stoplight Studio is a GUI editor for OpenAPI contracts. It is powerful and very easy to use. You can start with the free download, or even just the online version.
Make sure to select OpenAPI 3.0.x when creating a new contract in Stoplight Studio.
You can use it to run contract-based stubs just like you would use a spec file. Simply use the name of the OpenAPI yaml file wherever you would normally use the spec file, in
specmatic.json. You may also pass the yaml file to the Specmatic stub command —
specmatic stub api_order_v1.yaml. Nothing else changes.
_data directory works the same way it did with .spec files.
To see this in action, take a look at the sample consumer project.
To run contract tests, you’ll need to wrap the openapi yaml file in a thin Gherkin wrapper.
Note the line in the
Given openapi ./api_order_v1.yaml.
The rest of the file merely provides examples for the APIs found in
An API is identified by 3 identifiers:
- The URL path
- The method
- The response code
Each scenario in the wrapper must specify which the APIs it is providing examples for. To do this, it must provide the 3 identifiers to Specmatic.
All the Scenario Outlines in the sample spec file provide these 3 identifiers, examples for running the tests, and nothing more. No data structure definitions are needed in the spec file. Those are all imported from the yaml file declared in the
To see this in action, take a look at the sample API project.