API Documentation Using Swagger

API documentation is a crucial step in developing any service. It not only serves as a guide for developers but also as a key piece for the maintenance and evolution of projects over time. In this article, we will explore how to use Swagger to document APIs in Node.js, Java, C#, PHP, Golang, and Python, highlighting best practices, practical examples, and the benefits this approach can bring. We will also discuss how to use Swagger in the browser to make requests, similar to how Postman works.

Swagger is one of the most popular tools for API documentation. It uses the OpenAPI Specification (OAS) format, which is widely recognized and compatible with various languages and frameworks. One of Swagger’s strengths is its ability to generate an interactive interface, allowing developers to experiment with endpoints directly through the documentation. Let’s dive into the practical implementation.

Setting Up the Environment

To start, let’s create a basic Node.js application using Express. First, install the required dependencies:

npm install express swagger-jsdoc swagger-ui-express

swagger-jsdoc will generate the documentation based on comments in the code, and swagger-ui-express will serve as the visual interface for the documentation.

Structuring the Code

Here’s a basic example of how to configure your application and integrate Swagger:

const express = require('express');
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
const port = 3000;
// Swagger Configuration
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Example API',
      version: '1.0.0',
      description: 'A simple API to demonstrate best practices with Swagger',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'], // Path to Swagger comments in files
};
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
// Simple Routes
app.get('/api', (req, res) => {
  res.send('Welcome to the API!');
});
app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

This code sets up Swagger to serve documentation at http://localhost:3000/api-docs

Documenting Endpoints in Other Languages

Java Example

Using Spring Boot, configure Swagger with dependencies and annotations:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

And in the code:

@RestController
@RequestMapping("/users")
public class UserController {
  @GetMapping
  @ApiOperation(value = "List Users", notes = "Returns a list of users.")
  public List<User> getUsers() {
    return List.of(new User(1, "Alice"), new User(2, "Bob"));
  }
}

C# Example

In .NET Core, add Swagger to the project by installing the Swashbuckle package:

dotnet add package Swashbuckle.AspNetCore

And in the Startup.cs file:

public void ConfigureServices(IServiceCollection services) {
  services.AddControllers();
  services.AddSwaggerGen();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
  app.UseSwagger();
  app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1"));
}

PHP Example

Using Slim Framework with Swagger:

require 'vendor/autoload.php';
$app = new \Slim\App;
/**
 * @OA\Info(title="Example API", version="1.0")
 */
$app->get('/users', function ($request, $response, $args) {
    $users = [
        ["id" => 1, "name" => "Alice"],
        ["id" => 2, "name" => "Bob"]
    ];
    return $response->withJson($users);
});
$app->run();

Golang Example

Using Gin Framework and Swaggo:

package main
import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/gin-swagger/example/docs"
    ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
)
func main() {
    r := gin.Default()
    // @Summary List Users
    // @Produce json
    r.GET("/users", func(c *gin.Context) {
        c.JSON(200, []map[string]interface{}{
            {"id": 1, "name": "Alice"},
            {"id": 2, "name": "Bob"},
        })
    })
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run()
}

Python Example

Using Flask with Flask-Swagger:

from flask import Flask, jsonify
from flasgger import Swagger
app = Flask(__name__)
Swagger(app)
@app.route('/users', methods=['GET'])
def users():
    """
    Example endpoint to list users
    ---
    responses:
      200:
        description: List of users
    """
    return jsonify([{ "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" }])
app.run()

Using Swagger in the Browser

One of Swagger’s most useful features is the ability to make requests directly through the documentation interface. Similar to Postman, you can test endpoints, pass parameters, and view responses. This eliminates the need to switch between tools, speeding up debugging and development.

In the Swagger-generated interface, each documented endpoint is displayed with the necessary details, such as HTTP methods, descriptions, and input fields. Simply click “Try it out,” fill in the required fields, and send the request. Swagger will display the request sent, including headers and body, as well as the received response.

This functionality is particularly useful for integrating frontend and backend teams, allowing everyone to experiment with and understand APIs without relying on external tools.

Benefits of Automated Documentation

Documenting APIs with Swagger brings several benefits. One is consistency. By centralizing documentation directly in the code, the risk of outdated information is reduced. Additionally, the interactive interface makes understanding endpoints easier for both new developers and integration teams.

Another advantage is scalability. As your API grows, the documentation automatically keeps pace, provided the comments are well-written. This saves time and effort, especially in large or collaborative projects.

Best Practices

When using Swagger, some best practices can make a significant difference. Ensure clear and detailed descriptions for each endpoint. Avoid jargon or ambiguous terms that might confuse users. Additionally, include examples of requests and responses whenever possible. This helps clarify how the API should be used.

It’s also important to organize your documentation into categories. In the example above, we used the tags field to group related endpoints. This practice makes the interface more intuitive and easier to navigate.

While Swagger is a powerful tool, it does not replace careful planning. Documentation should be an extension of the API’s architecture, reflecting its intentions and functionalities clearly and accurately. By using Swagger and following these best practices, you can create APIs that not only work well but are also a pleasure to use.