Document APIs with Swagger (1/4) — Introduction

In this series of articles, I will introduce the different Swagger tools. Swagger is a very handy tool for API documentation. It allows you to generate “living” documentation, so that the documentation is always up to date, which is very difficult to do without this kind of tool. It also allows to generate code automatically, allowing the developer to focus on his core business. Finally, it is based on an open source specification format.

These articles focus on Swagger 2.0, while the 3.0 version (“OpenAPI 3.0.0”) is available.

This article is thus broken down into four parts :

The OpenAPI Specification (OAS) (https://www.openapis.org/) allows you to discover the functionalities of a service without having details about the code used to implement the API.

It is an Open Source interface independent of the language used to create the REST API created as part of the Linux Foundation.

The use case is that after writing the OpenAPI specification, you have an interactive documentation of the API.

The specification can be written in YAML or JSON.

The Swagger specification is available at https://Swagger.io/specification.

Swagger allows you to generate an API implementation in one of the supported languages from its specification. Many languages are supported.

This specification can be used by many other tools: Postman, AWS API Gateway, etc …

Here is a sample specification (swagger.yaml file):

cat <<EOF> swagger.yaml
swagger: "2.0"
info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"
host: "0.0.0.0:8080"
basePath:
schemes: ["http"]
tags:
- name: "Contact"
paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"
produces:
- "application/json"
responses:
200:
schema:
\$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
\$ref: "#/definitions/ContactCreateRequest"
responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"
definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
\$ref: "#/definitions/ContactResponse"
EOF

The corresponding specification is:

swagger: "2.0"
info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"
host: "0.0.0.0:8080"
schemes: ["http"]
tags:
- name: "Contact"
paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"
produces:
- "application/json"
responses:
200:
schema:
$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
$ref: "#/definitions/ContactCreateRequest"
responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"
definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
$ref: "#/definitions/ContactResponse"

Let’s study the structure of a Swagger file. A Swagger file can be in JSON or YAML format. So it describes the calls of the REST API.

The used version of Swagger :

swagger: "2.0"

The metadata about the API :

info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"

The address of the server on which the API is hosted:

host: "0.0.0.0:8080"

The base path of the API, relative to the value of host:

basePath:

The protocol used (HTTP or HTTPS):

schemes: "http"
tags:
- name: "Contact"

The path to the API or resources:

paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"

The types of Internet media used:

consumes:
- "*/*"

The types of Internet media generated:

produces:
- "application/json"

The type of response for the operation:

responses:
200:
schema:
$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"

The media types used:

consumes:
- "application/json"

The media types generated:

produces:
- "application/json"

Parameter details for an operation:

parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
$ref: "#/definitions/ContactCreateRequest"

The response type for the operation:

responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"

The input and output entity types for operations on API resources:

definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
$ref: "#/definitions/ContactResponse"

To get the full URL, Swagger concatenates basePath and paths.

For more information, see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md.

The used version of Swagger:

swagger: "2.0"

The metadata about the API:

info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"

The address of the server on which the API is hosted:

host: "0.0.0.0:8080"

The protocol used (HTTP or HTTPS):

schemes: "http"
tags:
- name: "Contact"

The path to the API or resources:

paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"

The media types used :

consumes:
- "*/*"

The media types produced:

produces:
- "application/json"

The response type for the operation:

responses:
200:
schema:
$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"

The media types used:

consumes:
- "application/json"

The media types produced:

produces:
- "application/json"

The parameter details for an operation:

parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
$ref: "#/definitions/ContactCreateRequest"

The response type for the operation:

responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"

The input and output entity types for operations on API resources:

definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
$ref: "#/definitions/ContactResponse"

In this first part, you understood the most important things to know about Swagger 2.0 specification.

More articles on my blog http://www.DevOpsTestLab.com.

My DevOpsTestLab Youtube channel.

My LinkedIn profile: https://fr.linkedin.com/in/brunodelb

Interests in the full lifecycle: design, Agile Coaching, development, testing, DevOps, Cloud, Management 3.0, ITIL. It defines me.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store