Generate API clients using Swagger

How to create SDK libraries a language of your choice

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

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.

Related content

Email APIs for Developers & QA

Build powerful applications and test suites using real email addresses in code. Create inboxes on demand then send and r...

Official MailSlurp documentation

Developer documentation and guides for MailSlurp's email APIs. REST, SDKS, Graphql, SMTP and more. MailSlurp is an email...

Ruby Mailer SDK - send and receive emails in Rails, Rspec an...

Receive email and attachments with Rails, Rspec, and Ruby without SMTP using MailSlurp Ruby Gem.

Temporary email api

Temporary email API for disposable email accounts. Free for personal use with REST API and clients in NodeJS, CSharp and...

Mailinator alternative

Alternatives to Mailinator for test email accounts. Create real email addresses using MailSlurp

Generate API clients using Swagger

How to create SDK libraries a language of your choice

Ready to dive in?Start building email applications today.