WireMock Cloud supports an OpenAPI mock API type that provides both incremental generation of stubs from OpenAPI and OpenAPI generation from stubs. Mock APIs of this type also have an associated auto-generated set of public documentation pages.

This supports two types of workflow:

  1. Automatic generation/amendment of a mock API from an existing OpenAPI doc as it evolves,
  2. API prototyping - defining API behaviour via stubs and auto-generating OpenAPI + documentation.

These workflows can be combined i.e. when prototyping new behaviour for an existing API.

​
Getting started

From the app’s home screen, create a new mock API and choose the OpenAPI type:

When the new mock API is created an extra item will be present on the left-hand nav bar, taking you to the OpenAPI editor page:

Navigating to the Settings tab on the same page, toggling on “Enable public API documentation” and clicking the link underneath will show the public API documentation (which will be initially empty apart from header information since there are no paths defined in the OpenAPI doc).

​
Generating stubs from OpenAPI

Stubs will be created or updated whenever changes are saved to the OpenAPI doc.

Add a new path entry and click Save:

Then navigate to the Stubs page and see that two new stubs have been created - one with specific request parameters required and one “default” i.e. will match regardless of specific parameter values provided the method and URL path are correct.

​
Updating an OpenAPI doc

When an OpenAPI doc is updated, for every path-method-status-contentType, existing stubs will be updated if any of the following apply:

  • The existing stub was generated from an example and the example hasn’t changed its name.
  • If there is one example within the given path-method-status-contentType which shares the response body with the existing stub.
  • If the path-method-status-contentType only provides a single example.
  • If the path-method-status-contentType doesn’t provide examples at all.

If none of the conditions above are satisfied, one or more stubs will be generated following the stub generation rules.

​
Stub generation rules

When updating an OpenAPI doc, the resulting stubs from new OpenAPI elements will be added. Stub generation will be based on the following rules:

  • 304 response:
    • Request header matcher If-None-Match with specific value 12345.
  • 422 response:
    • Only one stub will be generated, with a request body matcher not matching the schema or missing.
    • If more than one response example provided, it will pick one randomly as the response body.
    • If no response example provided, the response body will be autogenerated based on the schema.
  • 400 response:
    • Only one stub will be generated, with neither request parameters nor body present or matching the schema.
    • If more than one response example provided, it will pick one randomly as the response body.
    • If no response example provided, the response body will be autogenerated based on the schema.
  • Any other response status:
    • If no example is provided, it will generate a stub with autogenerated request parameters and response, based on schema.
    • If at least one example is provided:
      • It will generate one stub per example, using specific request parameter matchers and taking the example as the response body.
      • The request parameter matchers will be autogenerated based on the schema, unless the extension x-parameter-values is provided (as explained here), in which case it will be used to generate the expected values of the parameter matchers.

​
Default stubs

Optionally, for each path and method in the OpenAPI specification with a response status of 2xx, a “default” stub can also be generated. This default stub will not contain any specific request parameter matchers, only a request body matcher that matches the request body schema in the OpenAPI specification, if a schema is provided. To turn on/off the generation of default stubs, go to the Settings tab of the OpenAPI page, where the toggle is located.

​
Prototyping - generating OpenAPI from stubs

OpenAPI elements will be generated or updated when stubs are created or changed.

Try creating a stub with a new path template that doesn’t yet exist in the OpenAPI document:

On save, the path plus operation, responses, schemas and examples will be added to the OpenAPI spec and also to the public documentation.

Automatic generation of OpenAPI to stubs and vice versa can be turned off in the Settings tab of the OpenAPI page.

Configuring Rate LimitsImport OpenAPI