REST API - Documentation

There are some basic REST API features that are expected from any API, such as

1. Documentation
2. Content Negotiation
3. I18N
4. Versioning
5. HATEOAS
6. Serialization
7. Filtering

Let's deep dive one by one in this series, starting with Documentation.

API Documentation is technical content that describes the API in detail with instructions how to use and integrate the API along with constraints

The success of any API depends on the level of API adoption and utilization, and how to make the users and applications understand how to use the APIs. This largely depends on the clarity of the API documentation. One needs to document the API’s

1. Input – the schema
2. Output – the resources
3. Endpoint URL
4. Actions – verb of the HTTP method

OpenAPI helps in this process. It is a JSON format that explains/provides the details about the API, the input/output schema, the actions, restrictions on the schema, and much more.

OpenAPI defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

Based on this specification, Swagger is a tool that can provide a visual representation or a playground to understand the API in a clearer way. OpenAPI specification is also sometimes called Swagger Specification.

The basic structure of an OpenAPI document is:

? "openapi": "3.0.1",
? "info": {
? ? "title": "OpenAPI definition",
? ? "version": "v0"
? },
? "servers": [
? ? {
? ? ? "url": "https://localhost:8080",
? ? ? "description": "Generated server url"
? ? }
? ],
? "paths": {
? ? "/users": {
? ? ? "get": {
? ? ? ? "tags": [
? ? ? ? ? "user-resource"
? ? ? ? ],
? ? ? ? "operationId": "retrieveAllUsers",
? ? ? ? "responses": {
? ? ? ? ? "200": {
? ? ? ? ? ? "description": "OK",
? ? ? ? ? ? "content": {
? ? ? ? ? ? ? "*/*": {
? ? ? ? ? ? ? ? "schema": {
? ? ? ? ? ? ? ? ? "type": "array",
? ? ? ? ? ? ? ? ? "items": {
? ? ? ? ? ? ? ? ? ? "$ref": "#/components/schemas/User"
? ? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? }
? ? ? ? ? ? }
? ? ? ? ? }
? ? ? ? }
? ? ? },
? ? ? "post": {
? ? ? ? "tags": [
? ? ? ? ? "user-resource"
? ? ? ? ],
? ? ? ? "operationId": "createUser",
? ? ? ? "requestBody": {
? ? ? ? ? "content": {
? ? ? ? ? ? "application/json": {
? ? ? ? ? ? ? "schema": {
? ? ? ? ? ? ? ? "$ref": "#/components/schemas/User"
? ? ? ? ? ? ? }
? ? ? ? ? ? }
? ? ? ? ? },
? ? ? ? ? "required": true
? ? ? ? },
? ? ? ? "responses": {
? ? ? ? ? "200": {
? ? ? ? ? ? "description": "OK",
? ? ? ? ? ? "content": {
? ? ? ? ? ? ? "*/*": {
? ? ? ? ? ? ? ? "schema": {
? ? ? ? ? ? ? ? ? "$ref": "#/components/schemas/User"
? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? }
? ? ? ? ? ? }
? ? ? ? ? }
? ? ? ? }
? ? ? }
? ? },
? ? "/users/{id}": {
? ? ? "get": {
? ? ? ? "tags": [
? ? ? ? ? "user-resource"
? ? ? ? ],
? ? ? ? "operationId": "getOne",
? ? ? ? "parameters": [
? ? ? ? ? {
? ? ? ? ? ? "name": "id",
? ? ? ? ? ? "in": "path",
? ? ? ? ? ? "required": true,
? ? ? ? ? ? "schema": {
? ? ? ? ? ? ? "type": "integer",
? ? ? ? ? ? ? "format": "int32"
? ? ? ? ? ? }
? ? ? ? ? }
? ? ? ? ],
? ? ? ? "responses": {
? ? ? ? ? "200": {
? ? ? ? ? ? "description": "OK",
? ? ? ? ? ? "content": {
? ? ? ? ? ? ? "*/*": {
? ? ? ? ? ? ? ? "schema": {
? ? ? ? ? ? ? ? ? "$ref": "#/components/schemas/EntityModelUser"
? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? }
? ? ? ? ? ? }
? ? ? ? ? }
? ? ? ? }
? ? ? }
? ? },
? ? "delete": {
? ? ? "tags": [
? ? ? ? "user-resource"
? ? ? ],
? ? ? "operationId": "deleteUser",
? ? ? "parameters": [
? ? ? ? {
? ? ? ? ? "name": "id",
? ? ? ? ? "in": "path",
? ? ? ? ? "required": true,
? ? ? ? ? "schema": {
? ? ? ? ? ? "type": "integer",
? ? ? ? ? ? "format": "int32"
? ? ? ? ? }
? ? ? ? }
? ? ? ],
? ? ? "responses": {
? ? ? ? "200": {
? ? ? ? ? "description": "OK"
? ? ? ? }
? ? ? }
? ? }
? },
? "components": {
? ? "schemas": {
? ? ? "User": {
? ? ? ? "type": "object",
? ? ? ? "properties": {
? ? ? ? ? "name": {
? ? ? ? ? ? "maxLength": 2147483647,
? ? ? ? ? ? "minLength": 2,
? ? ? ? ? ? "type": "string"
? ? ? ? ? },
? ? ? ? ? "birthDate": {
? ? ? ? ? ? "type": "string",
? ? ? ? ? ? "format": "date"
? ? ? ? ? }
? ? ? ? }
? ? ? }
    }
  }
}         

OpenAPI has the following merits:

1. Clear documentation
2. Language-agnostic
3. Widely adopted
4. More tools to support the documents

But, OpenAPI is less useful when it comes to API designing and planning. Using the OpenAPI document, one can use tools like Swagger to display it as easily understandable content.

The Spring Boot group ID to generate the Swagger playground based on this OpenAPI document is org.springdoc. The Artifact ID is: springdoc-openapi-starter-webmvc-ui

The pom.xml looks like this:

The basic steps to generate the API documentation are:

1. Create the Spring Boot application to implement the API as per needs
2. Include the dependency
3. Access https://localhost:8080/swagger-ui/index.html to get a swagger playground to understand the APIs

4. Access https://localhost:8080/v3/api-docs to understand the OpenAPI specification

Please find the video to understand how it works:

Find the code on GitHub here.