# Generating API clients using Swagger
MailSlurp's REST API has built in Swagger/OpenAPI support. That means MailSlurp provides an API specification file (opens new window) 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 (opens new window). The format is basically a way of listing every HTTP endpoint in an API and the requests and responses expected.
The MailSlurp swagger definition (opens new window) 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 (opens new window) 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 (opens new window)
# 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.
