API Documentation With Swagger

Raj Kumar Shrestha
Apr 19, 2017 · 3 min read

Documentation is a set of documents provided on paper, or online, or on digital or analog media, for example, quick-reference guides. As a developer, it is very important to have reliable documentation about your work. It helps to jump into any development, maintenance and knowledge transfer of application. Most importantly, it is very helpful for other developers to understand programming code and application.

Application Programming Interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact. Most of the applications today are the web application and powered by API. Therefore, it is very important that API needs to be well documented to be understood and consumed by another developer.

There are multiple tools to document API, here I am going to start with Open API Initiative-Swagger. Swagger is simple and easier to write and is easy to consume from developer to developer. I am not going to talk about all the features, pros and cons of swagger.

Now, let’s start API documentation with swagger in YAML. You can write your document in your favorite text editor or you can use swagger-editor.

If you are using text editor then create a file user.yml.

Firstly, we add generic information about our api.

# this is an example of the Users API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
title: Sample API
description: Users rest API
version: "1.0.0"
# the domain of the service
host: api.sample.com
# array of all schemes that your API supports
schemes:
- https
# will be prefixed to all paths
basePath: /v1
produces:
- application/json

Then we will add details about each API path which falls under paths: tag.

paths:
/users:
post:
summary: Create User
description: |
Create a new user
tags:
- Users
parameters:
- name: body
in: body
schema:
$ref: '#/definitions/CreateUserRequest'
responses:
201:
description: Created
schema:
$ref: '#/definitions/UserResponse'

Here, I am creating create user API along with its request parameters and response.

Definitions are path templating and referenced by $ref tag. CreateUserRequest and UserResponse are defined under definitions section and their paths are referenced to request parameters and responses.

definitions:
FirstName:
type: string
description: First name of user
example: Raj
LastName:
type: string
description: Last name of user
example: Shrestha
Age:
type: integer
minimum: 1
maximum: 200
example: 27
Education:
type: array
items:
type: object
properties:
level:
type: string
description: Education level
score:
type: string
description: Score
example: [{level: 'Bachelor', score: '3.0'}]
CreateUserRequest:
type: object
properties:
first_name:
$ref: '#/definitions/FirstName'
last_name:
$ref: '#/definitions/LastName'
age:
$ref: '#/definitions/Age'
education:
$ref: '#/definitions/Education'
required:
- first_name
- age
UserResponse:
type: object
properties:
first_name:
$ref: '#/definitions/FirstName'
last_name:
$ref: '#/definitions/LastName'
age:
$ref: '#/definitions/Age'
education:
$ref: '#/definitions/Education'

In definitions, I have also made templates of users element which helps us to reduce repetitive work and update easily.

In the final document, we will put all together. You can also view this on gist. We have created a create user API. Similarly, we can build other APIs. In the beginning, it feels a little boring and time waste, but, after playing with the swagger documentation you will enjoy developing APIs.

In the next part, I will describe each part of the tags and UI for rendering swagger document. Stay Tuned.

Raj Kumar Shrestha

Written by

Software engineer @theCloudFactory

Shabda शब्द (words)

blogging

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade