Overview

Introduction

Despite its 7+ years old, Swagger (aka as OpenAPI v2) is still a very popular specification format for REST APIs. Eventhough its OpenAPI v3 descendant is now well established and provides more comprehensive way of describing things, Swagger v2 is still very present.

Starting with version 1.5.1, Microcks is supporting Sxwagger mocking and testing thanks to the new multi-artifacts support feature. In order to use Swagger in Microcks, you will need 2 artifacts for each API definition:

• A Swagger definition that holds the API metadata and operations definitions,
• A Postman Collection file that holds the mock examples (requests and responses) for the different operations of the API.

Conventions

In order to be correctly imported and understood by Microcks, your Postman file should follow a little set of reasonable conventions and best practices.

• Your Postman collection description will need to have a name that matches the API name and a custom property version that matches the API version. As of writing, Postman does not allow editing of such custom property although the Collection v2 format allow them. By convention, we allow setting it through the collection description using this syntax: version=1.0 - Here is now the full description of my collection....
• Your Postman collection will need to organize examples into requests having the same url as the Swagger paths and verbs. The comparison is realized apart the path templating characters. Eg. in Swagger you may have a GET /path/{param} operation, the Postman request with GET verb and /path/:param url will be considered as equivalent.
• Your Postman collection will then simply hold examples, defining the value for all different fields of a requeest/response pair.

We recommend having a look at our sample Swagger API for the Beer Catalog API as well as the companion Postman collection to fully understand and see those conventions in action.

Illustration

Let’s dive in details of our sample Beer Catalog API.

Specifying API structure

This is a fairly basic Swagger API. You can see below an excerpt of the the definition using Swagger below found in BeerCatalogAPI-swagger.json file and defining 3 operations:

{
  "swagger": "2.0",
  "info": {
    "title": "Beer Catalog API",
    "version": "0.99"
  },
  "paths": {
    "/beer": {
      "get": {
      }
    },
    "/beer/{name}": {
      "get": {
      }
    },
    "/beer/findByStatus/{status}": {
      "get": {
      }
    }
  }
}

Considering the first comment line of this file, when imported into Microcks, it will discover the Beer Catalog API with version 0.99 and 3 operations that are: GET /beer, GET /beer/{name} and GET /beer/findByStatus/{status}.

Specifying API examples

Specification of examples is done using a Postman Collection as examples cannot be attached to main Swagger and thanks to Microcks 1.3.0 multi-artifacts support feature.

Using Postman, just create a new Collection - using the same name as Swagger API and adding the custom property version at the beginning of description like illustrated below:

You can now start organizing and creating requests those verb and url are matching with the Swagger API operation path and verbs. For our example, we’re specifying the three operations: GET /beer, GET /beer/{name} and GET /beer/findByStatus/{status}.

Note in the example above that Microcks doesn’t care on Postman request name but checks the verb and the url. Here we define request and attached examples for the Swagger GET /beer/{name} operation. The ehcked parts are the verb (GET here) and the url (/beer/:name is equivalent to /beer/{name} path).

You may then define different examples for each request. Below is a basic example but Templating expressions and functions are obviously supported:

Importing artifacts

Both artifacts should be imported into Microcks either through direct upload or scheduled import . The important thing to notice is that the Swagger specification artifact represents the main or primary artifact for this service definition and that the Postman Collection represents a secondary artifact. You have to mention it when importing it otherwise your API definition will be overwritten!