API documentation using Swagger
What Is API Documentation?
API documentation is technical content that documents the API. It includes instructions on how to effectively use and integrate the API. It also provides updates on the API’s lifecycle such as new versions or retirement. Some aspects of API documentation can be generated automatically via Swagger or other documents.
Let’s start with clarifying Swagger vs OpenAPI
The easiest way to understand the difference is:
- OpenAPI = Specification
- Swagger = Tools for implementing the specification
OpenAPI Specification (formerly known as Swagger Specification) is an open-source format for describing and documenting APIs.
The Specification was originally developed in 2010 by Reverb Technologies (formerly Wordnik) as a way to keep the API design and documentation in sync.
The latest version of OpenAPI is 3.0. OpenAPI definitions can be written in JSON or YAML. We recommend YAML, because it is easier to read and write.
Prerequisites
- Basic knowledge of RESTful APIs.
- Basic knowledge of YAML is recommended.
Create an API
An API defined using the OpenAPI Specification can be divided into 3 main sections –
- Meta information
- Path items (endpoints):
- Parameters
- Request bodies
- Responses
3. Reusable components:
- Schemas (data models)
- Parameters
- Responses
- Other components
Meta information
Let’s start with a simple API definition that contains just meta information, such as the API title, version, server URL and other descriptive information.
All keyword names are case-sensitive.
openapi: 3.0.0
info:
version: 1.0.0
title: Simple Artist API
description: A simple API to illustrate OpenAPI conceptsservers:
- url: https://example.io/v1# Basic authentication
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []paths: {}
Info
Each API definition starts with the version of the OpenAPI Specification that this definition uses. In our example, it is openapi: 3.0.0. The info object contains the API title and version, which are required, and an optional description.
Servers
The servers array specifies one or more server URLs for API calls. The API endpoint paths are appended to the server URL. Some APIs have a single server, others may have multiple servers, such as production, staging and sandbox. In our example, the server URL is https://example.io/v1.
Security
We also secure the API using Basic authentication, so that only authorized users can consume the API.
Supported authentication methods are:
- HTTP authentication: Basic, Bearer, and so on.
- API key as a header or query parameter or in cookies
- OAuth 2
- OpenID Connect Discovery
Path
The path items are the endpoints of your API under which you can specify HTTP verbs for manipulating the resources in the desired manner. These endpoints are relative to the server URL, which in our example is https://example.io/v1.
We will define the /artists endpoint and the GET method for this endpoint. So, a client will use GET https://example.io/v1/artists to get a list of artists.
openapi: 3.0.0
info:
version: 1.0.0
title: Simple API
description: A simple API to illustrate OpenAPI conceptsservers:
- url: https://example.io/v1components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []# ----- Added lines ----------------------------------------
paths:
/artists:
get:
description: Returns a list of artists
# ---- /Added lines ----------------------------------------
Responses
Every response would need at least one HTTP status code to describe the kind of responses a consumer is likely to expect. The description gives details on what the responses of the API would be. In our sample code, we have specified 200, which is a successful client request, while 400 is an unsuccessful request.
openapi: 3.0.0
info:
version: 1.0.0
title: Simple API
description: A simple API to illustrate OpenAPI conceptsservers:
- url: https://example.io/v1components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []paths:
/artists:
get:
description: Returns a list of artists
# ----- Added lines ----------------------------------------
responses:
"200":
description: Successfully returned a list of artists
content:
application/json:
schema:
type: array
items:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string "400":
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ---- /Added lines ----------------------------------------
Parameters
Operations can have parameters passed via URL path (/users/{userId}), query string (/users?role=admin), headers (X-CustomHeader: Value) or cookies (Cookie: debug=0). You can define the parameter data types, format, whether they are required or optional, and other details:
Query parameters
Query parameters appear at the end of a URL following a question mark. Query parameters are optional and non unique, so they can be specified multiple times in the URL. It is a non-hierarchical component of the URL.
GET https://example.io/v1/artists?limit=20&offset=3Request body
POST, PUT and PATCH requests typically contain the request body. The request body is defined by using the requestBody object. For this API, let’s add the ability for a user to post an artist to our database. This would be under the /artists resource.
Path parameters
The path parameters can be used to isolate a specific component of the data that the client is working with, for example, https://example.io/v1/artists/{username}. Path parameters are part of the hierarchical component of the URL, and are thus stacked sequentially.
Reusable components
The Specification defines various types of reusable components:
- Schemas (data models)
- Parameters
- Request bodies
- Responses
- Response headers
- Examples
- Links
- Callbacks
