Skip to main content Link Search Menu Expand Document (external link)

OpenAPI Support

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.

Getting Started

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.

Writing Contracts

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.

Stubbing Out Contracts

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.

The _data directory works the same way it did with .spec files.

To see this in action, take a look at the sample consumer project.

Contract Tests

To run contract tests, you’ll need to wrap the openapi yaml file in a thin Gherkin wrapper.

See the yaml contract projects, and the thin wrapper spec file.

Note the line in the Background saying Given openapi ./api_order_v1.yaml.

The rest of the file merely provides examples for the APIs found in api_order_v1.yaml.

An API is identified by 3 identifiers:

  1. The URL path
  2. The method
  3. 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 Background section.

To see this in action, take a look at the sample API project.