Skip to content

Latest commit

 

History

History
72 lines (47 loc) · 2.63 KB

openapi_plugin.md

File metadata and controls

72 lines (47 loc) · 2.63 KB
Raw

OpenAPI (aka Swagger) plugin

Plugin class: com.gatehill.imposter.plugin.openapi.OpenApiPluginImpl

The plugin provides support for OpenAPI (aka Swagger) specifications.

Features

  • Creates mock endpoints from OpenAPI/Swagger 2 API specifications.
  • Serves response examples embedded in the specification.
  • Also supports static response files and script-driven responses, using status code, response files etc.
  • Provides an interactive API sandbox at /_spec

Configuration

Read the Configuration section to understand how to configure Imposter.

Additional context objects

Object Type Description
operation io.swagger.models.Operation The OpenAPI operation for the request.

Using the plugin

A great way to use this plugin is to take advantage of the built in examples feature of OpenAPI/Swagger files. These provide a standard way to document sample responses for each API response. This plugin will match the example to serve using a combination of:

  • matching URI/path
  • matching content type in Accept HTTP request header to the produces property of the response
  • matching status code to the response

Typically you will use a simple script (see plugin/openapi/src/test/resources/config for working example) to control the status code, and thus the content of the response.

You can also use the interactive API sandbox at /_spec; e.g. http://localhost:8443/_spec, which looks like this:

API sandbox

Example

For working examples, see:

plugin/openapi/src/test/resources/config

Let's assume your configuration is in a folder named config.

Docker example:

docker run -ti -p 8443:8443 \
    -v $(pwd)/config:/opt/imposter/config \
    outofcoffee/imposter-openapi \
    --plugin com.gatehill.imposter.plugin.openapi.OpenApiPluginImpl \
    --configDir /opt/imposter/config

Standalone Java example:

java -jar distro/build/libs/imposter.jar \
    --plugin com.gatehill.imposter.plugin.openapi.OpenApiPluginImpl \
    --configDir ./config

This starts a mock server using the OpenAPI plugin. Responses are served based on the configuration files inside the config folder; in particular the Swagger specification petstore-expanded.yaml.

Using the example above, you can interact with the APIs with examples in the Swagger specification at their respective endpoints under http://localhost:8443/<endpoint path>.

For specific information about the endpoints, see the interactive sandbox at http://localhost:8443/_spec.