Design APIs Easier than Ever with SWAGGER 2.0

As promised in my last blog post about “Open API Initiative and the Future of API Space with the Open API Specification”, in this blog post I am going to explain how to design a complete API with Swagger 2, the world standard language for designing and documenting APIs. For the people who are new to Swagger, I will explain a bit about Swagger 2.

Swagger 2 is originally introduced by SmartBear Software and later they donated it to the Open API Initiative which now maintains this world standard API definition language.

In this blog post, I expect to explain how to design a simple, but a complete API using Swagger 2 specification. I will try to explain as simple as possible for everyone to understand. That’s enough with it, now let’s start designing an API.

For your convenience, I will break this article in to 9 parts.

  1. Overview of Swagger 2.0
  2. Basic Structure
  3. Metadata
  4. Base URL
  5. Consumes, Produces
  6. Paths and Operations
  7. Parameters
  8. Responses
  9. Input and Output Models

1. Overview of Swagger 2.0

Before writing the specification, it is good to understand the overview of the structure of Swagger 2.0. Here you can see the structure of Swagger 2.0 in an understandable way. You will know what they mean and how to write these sections in the definition in this article. Keep reading.

https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

2. Basic Structure

Swagger can be written in either JSON or YAML. In this article, I will explain in YAML. But you can write it in JSON as well. They are quite similar. If you need to convert from YAML to JSON or wise versa, use this web tool.

I will now explain the basic structure of a Swagger 2.0 specification. All parts of this structure is required to make a complete API. Only with these basic elements, you can write an API. Here is a most basic API specification written in Swagger 2.0.

Basic Swagger Specification for a sample PetAPI

Now, I will this element by element. This basic structure contains 6 main elements listed, swagger, info, host, basePath, schemes, paths. Without any of these elements, we cannot write a Swagger definition for an API. All these elements are essential for writing a complete API specification.

3. Metadata

The ‘ swagger: “2.0” ’ element explains this is a Swagger 2.0. The value of this element must be 2.0. Therefore, this element is essential.

The swagger element

The “info: “ element explains the title, description and version. This element is an essential element for the specification as all the metadata about the API is in this section.

  • title : This is a required element in info element. The type is “string” and this describes the title of the application.
  • description : Type of “string”. Includes a short description about the application.
  • version : A required element. Type of “string”. Includes the version of the API. Not the specification version.

These are the basic sub elements of the “info” element. For more sub elements of the “info” element, visit here.

The info element

4. Base URL

There is a URL that every REST API paths are appended. The host, basePath and schemes elements describes the parts of this URL. The paths in the definition are actually relative to this URL. For an instance, in the above basic definition, the /pets path is represented like below,

<scheme>://<host>/<basePath>/pets

These elements serves the following purposes,

scheme : These are the transfer protocols used by the API. Swagger 2.0 supports both http and https.

host : The domain name or the IP address of the host that serves the API.

basePath : This prefixes all the paths(will be discussed) defined in the Swagger definition and this is relative for the host. This must be defined in the Swagger definition with a leading slash.

Here is an example,

Elements of the base URL

5. Consumes/ Produces

An API accepts and returns data when a request is made. Some API calls only accepts data and some do both accepting and returning. Consumes and Produces elements define the format of the data that the API accepts and returns. These are called MIME types. These MIME types can be defined globally(root level of the API) or locally for individual operations(Will be discussed in the Paths section).

The following MIME types can be defined in a Swagger 2.0 definition.

MIME types compliant with RFC 6838

Here is an example global MIME type definition for both JSON and XML types.

Global MIME type definition

6. Paths and Operations

The “path” element plays an important role in the API specification. Inside this element, we can define what are the resources or individual endpoints of the API and what are the HTTP methods used for those endpoints.

The paths can be defined in global paths section of the definition. Remember all these paths are relative to the basePath that is defined earlier in the definition. Here’s how this happen.

scheme::/host/basePath/path

This is how the paths are defined in global paths section in the definition.

paths defined in the global paths section of the definition

As I mentioned in section 5, we can define MIME types locally for a particular API like this,

MIME type defined locally in /cats API

You can also define “tags” to group your APIs in a way you want. For doing this, under the resource you defined(/cats here), define a “tags” element and give a tag name you want.

6.1 Path Templating

There are times the paths are needed parameters. Where the value can be a variable. In situations like these, there is this feature in Swagger 2.0 to define variable parameters in paths.

The variable part of the path can be defined in curly braces so the definition recognizes that it is a variable parameter which is pointed to a particular resource of the data collection. Here are some examples.

Paths defined with variable parameters

6.2 Operations

When you define paths in the definition, you need the relative HTTP methods for each path. Swagger 2.0 supports the following HTTP methods. These HTTP methods are called “operations” in Swagger.

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • HEAD
  • OPTIONS

A single path can contain multiple operations. Swagger defines a unique operation as a combination of a path and an HTTP method. This means you cannot define two GET methods or two POST methods for the same path even if they have different parameters.

Here is a simple path with GET operation.

A simple path with GET operation

These operations support some optional elements for documentation purposes.

  • summary : a short summary about the operation
  • description : a longer description about the operation(this can be multi lined and GitHub flavored markdown)
  • tags : used to group operations in swagger UI
  • externelDocs : allows to refer additional external docs

7. Parameters

Parameters in Swagger are defined in the parameters section under the operation of the path. The “parameters” section is an array so the elements of it must be defined as as array. There are several types of parameters and they have the following elements.

  • name : name of the parameter
  • type : type of the parameter(for primitive value parameters)
  • schema : for request body
  • description : a short description about the parameter

Here is a path defined with a path parameter. (The parameter types will be discussed)

Path parameter “catId”

7.1 Parameter Types

The parameter types are defined in Swagger according to the location of the parameter. This is defined in the element “in” under the “parameters” section. This can be either “query” or “path”.

7.1.1 Query Parameters

Query parameters appear at the end of the URL after question mark (?) with different name values pairs separated with ampersands (&). These can be “required” or not.

The required element comes under the parameters section to tell if the parameter is required for the request or not. The values of the “required” key is boolean.

Eg : /cats?Id=123

Example parameter section for a query parameter

7.1.2 Path Parameters

Example parameter section for a path parameter

Note how the “in” key varies between the query and path parameter definitions. Using a path parameter, we can point the request to a certain resource. The path parameter is required, so you need to define the required element as true. The parameter is specified in a pair of curly brackets. Here is a simple example for a path parameter.

Eg: /cats/{catId}

8. Responses

The “responses” section allows you to define the response format or type you expect from different APIs. This is defined under the “path” element and after the parameter definition(if any). You can also specify what is the response code you want as the response of the particular API. You can also add a brief description for the response. The “schema” keyword is used to define the response body.

The “schema” can define,

  • a primitive type(string or integer)
  • an object of array type (with JSON or YAML APIs) — Under “properties” element, you can define elements of the object body.

Here is an example response element,

example response element

A response body also can be defined in the “definitions” section(Will be discussed under Input and Output Models). For doing this we have to use “$ref” element under the “schema” element in the response section. Usually, this “definitions” section is used when a response body of request body definition is used globally in the API definition. An example is given below,

A response section with body definition directed “Cat” definition section

9. Input and Output Models

In the “definitions” section, both response bodies and request bodies of the APIs can be defined. The definition of ……. let’s say, the response body of a defined API is directed to “Cat” definition in the “definitions” section using “$ref” element under the “schema” keyword as discussed in previous section, when defining the “Cat” definition in the “definitions” section, we have to use the same name that used to point in the response section(i.e “Cat”). Here is the definition of “Cat” response body,

Response body definition of “Cat” definition with two properties

To wrap up, here is the whole API definition we designed here, you can get a better understanding by looking at this and reading comments that I have applied to according to the sections we have discussed.

API definition discussed in this article

You can use Swagger Editor to validate the definition you wrote. The Swagger Editor can also be used to generate the REST API client code for you to use it in your own applications.

There are so many other things that can be included in a Swagger 2 API definition. This is to provide you the basic guides to write a simple and complete API definition using Swagger 2 API definition language. The content is taken from official Swagger Website and you can always find more from the page. The Swagger 3 is always available for designing APIs with new features. You can use the foundation that you will get by reading this for designing APIs using Swagger 3 specification. Good luck designing APIs.

And please give me a clap if you really got something out of this. It really means. Hope to see you with a new article. :-)