Generating API clients using Swagger or OpenAPI

MailSlurp's REST API has built in Swagger/OpenAPI support. That means MailSlurp provides an API specification file from which you can generate code libraries in the languages of your choice. This article will explain how MailSlurp describes their API and how you can use the resulting swagger.json with swagger-codegen.

Describing your API

To generate code with Swagger you need a description of an API. This description should be in the OpenAPI/Swagger format. The format is basically a way of listing every HTTP endpoint in an API and the requests and responses expected.

The MailSlurp swagger definition is a JSON object with the following structure:

{
  "swagger": "2.0",
  "info": {
    "title": "MailSlurp API",
    "version": "6.5.2"
  },
  "host": "api.mailslurp.com",
  "basePath": "/",
  "paths": { ...apiPaths }
}

The paths object contains a description of all the API endpoints available. The descriptions will be used later to generate method signatures in API client code. Each path key looks a bit like this:

{
  "/domains/{id}": {
    "get": {
      "operationId": "getDomain",
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "id",
          "required": true,
          "type": "string",
          "format": "uuid"
        }
      ],
      "responses": {
        "200": {
          "description": "OK",
          "schema": {
            "$ref": "#/definitions/Domain",
            "originalRef": "Domain"
          }
        }
      },
      "security": [
        {
          "API_KEY": []
        }
      ]
    }
  }
}

Notice in the responses field their is a return object definition { "$ref": "#/definitions/Domain" }. This reference is used to generate model classes for request and response payloads in the generate code.

Generating code

Once you have a swagger spec for a given API you can use the swagger-codegen cli to generate a library in the language of your choice for interacting with said API.

Download Swagger Spec

curl -L -o swagger.json https://swagger.mailslurp.com

Install Swagger Codegen

OSX: brew install swagger-codegen
Others: See README instructions

Execute the Swagger CLI

swagger-codegen-cli generate -i swagger.json -l java -o mailslurp-client

The results will be a folder containing a generated Java library for calling the MailSlurp API with fully typed requests, responses, and methods.