OpenAPI Mocking and Prototyping

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 “generic” 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 not satisfied, one or more stubs will be generated following the Stubs generation rules

Stubs generation rules

1. 304 response, request header If-None-Match with specific value 12345
2. 2xx responses with specific parameters
   • If no example is provided in the OpenAPI doc, 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 parameters and taking the example as response
     • The request parameters 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.
3. 2xx with generic parameters
   • Only one stub will be generated with generic request parameters/body.
     • If more than one response example provided, it will pick one randomly as response.
     • If no response example provided, the response will be autogenerated base on the schema.
4. 422 response (Only one stub will be generated)
5. 400 response (Only one stub will be generated)
6. The rest of the responses will be treated with the same priority.
   • 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 parameters and taking the example as response
     • The request parameters 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.

Stub generation rules

When updating an OpenAPI doc, the resulting stubs from new OpenAPI elements will be added and existing stubs will be updated.

• When working with response examples, the strategy for determining the appropriate stub to create/update will be based on the example name and response body, following these rules:
  • If we are adding a single example, where there wasn’t any previously, it will update the existing stubs related to the path/operation/content.
  • If we are moving an existing single (not named) example to a named example (keeping the response content), it will update the existing stubs related to the previous single example and will link it to the new named one.
  • If we didn’t have any examples and we create a new named example, it will generate new stubs and keep the old ones (this behaviour will change in next releases, so the existing stubs will be updated).
• Stub generation will be based on the following rules with descending priorities:
  1. 304 response, request header If-None-Match with specific value 12345
  2. 2xx responses with specific parameters
     • If no example is provided in the OpenAPI doc, 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 parameters and taking the example as response
       • The request parameters 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.
  3. 2xx with generic parameters
     • Only one stub will be generated with generic request parameters/body.
     • If more than one response example provided, it will pick one randomly as response.
     • If no response example provided, the response will be autogenerated base on the schema.
  4. 422 response
     • Only one stub will be generated, with request body not matching schema or missing
     • If more than one response example provided, it will pick one randomly as response.
     • If no response example provided, the response will be autogenerated base on the schema.
  5. 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 response.
     • If no response example provided, the response will be autogenerated base on the schema.
  6. The rest of the responses will be treated as equal, at the same priority.
     • 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 parameters and taking the example as response
       • The request parameters 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.

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.