Swagger Made Simple: A Walkthrough of API Documentation

In software development , APIs enable communication between different applications, acting as a bridge between systems. Without proper documentation, APIs are hard to use.

Backend developers create APIs, and frontend developers integrate them into the UI. To do this, they need API specifications. API documentation is a guide that explains how to use the API, including making requests, sending data, handling responses, and errors.

The API documentation helps developers:

• Understand the available endpoints and their functions.
• Know the request parameters and data formats.
• Properly handle responses and errors.

Here's where Swagger is useful. It's part of an openAPI Intiative. Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs.

OpenAPI

What is OpenAPI Specifications ?

The OpenAPI Specification (OAS) is used to define the details of REST API's, like the available endpoints, how requests and responses should be formatted, what parameters are needed, and how authentication works. Normally, OpenAPI descriptions are written in either YAML or JSON.

Building Blocks of Open API specifications

In the diagram below you can see an overview of the building blocks of the OpenAPI Specification. The green boxes are the mandatory fields and the orange ones are optional.

1.openapi: The version of the OpenAPI specification being used (mandatory).

2.info: Information about the API, like title, version, and description (mandatory).

3.servers: Defines the servers where the API is hosted (optional).

4.paths: Lists the available API endpoints and their operations (mandatory).

5.components: Holds various reusable components, such as schemas (data models) , parameters etc (optional).

6.security: Defines authentication mechanisms for the API, like API keys, OAuth, or HTTP-based auth (optional).

7.tags: The tags section is used to group operations logically for better organization(optional).

8.externalDocs: Allows you to include links to external documentation for additional information on specific parts of the API. (optional).

SWAGGER

Let's take a look at the history of Swagger.

Swagger originally started as an open-source project in 2010 by SmartBear Software .In 2015, it was contributed to the OpenAPI Initiative. This initiative is backed by IT big giant's like Amazon, Google, and the Linux Foundation.

Today, APIs are developed using OpenAPI specifications, and Swagger is a toolset used for designing, building, and documenting APIs that follow the OpenAPI standards.

Let's meet some swagger tools ...

1. Swagger UI

Swagger UI is a web tool that automatically creates interactive API documentation. It allow developers and users test the API by sending requests and seeing the results directly in the browser. Think of it as a live manual for your API.

Check out this swagger live demo. You can understand it better by interacting with it.

2. Swagger Editor

Swagger Editor is a browser tool where you can write or edit API specifications using simple text (in YAML or JSON format). It helps you to create the API documentation.

3. Swagger Codegen

Swagger Codegen is a tool that generates code from your API specifications. It creates templates for server or client apps in various languages, saving time by providing a base for API integration.

4. SwaggerHub

SwaggerHub is a collaborative platform for designing, building, and managing APIs using the OpenAPI Specification. It combines tools like Swagger UI, Editor, and Codegen in one place,making it easier for teams to work together on API projects.

It's better to think of Swagger as similar to Postman or Hoppscotch, but Swagger primarily focuses on API design and documentation, while Postman and Hoppscotch are more focused on API testing, development, and debugging.

Integrate Swagger in Your Spring boot Project.

You can integrate Swagger into a Spring Boot project using either Springfox or Springdoc. However, it appears that the Springfox project is no longer actively maintained, with no commits in the last four years and no updates to accommodate newer technologies like Jakarta EE or Spring Boot 3.

We can use Springdoc, which I think is easier to set up.

To integrate Swagger into your Spring Boot project, add this dependency to your pom.xml:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.6</version> <!-- Replace with the latest version -->
</dependency>

After that, you can access the Swagger UI at :
http://localhost:8080/swagger-ui/index.html

In the UI, you can view all your endpoints, schemas, and API information. To see the API documentation in JSON format, visit :
http://localhost:8080/v3/api-docs

For advanced documentation, Springdoc provides a variety of useful annotations. Let's take a look at some of them:

1. @Operation

This annotation is used to document individual API operations. It provides information like the summary, description, and response types.

@Operation(
    summary = "Get all Employees",
    description = "Returns a list of all Employees”
)
    @GetMapping
    public List<Employee> getAllEmployee(){
        return employeeService.getAllEmployee();
    }

2. @ApiResponses and @ApiResponse

These annotations are used to specify possible HTTP responses for an operation, including different response codes and descriptions.

 @DeleteMapping("/{id}")
    @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Employee Deleted"), @ApiResponse(responseCode = "404", description = "Employee not found") })
    public void deleteEmployee(@PathVariable int id){
        employeeService.deleteEmployee(id);
    }
}

3. @Parameter

This annotation is used to describe a specific request parameter or path variable. You can provide details such as whether the parameter is required or optional, along with a description of its purpose.

@GetMapping("/{id}")
public Optional<Employee> getEmployeeById(
    @Parameter(description = "ID of the Employee to be retrieved", required = true)
    @PathVariable int id){
    return employeeService.getEmployeeById(id);
}

4. @Tag

Used to group related operations in the documentation.

@Tag(name = "Employees", description = "Operations related to Employees")
@RestController
@RequestMapping("/employee")
public class EmployeeController {
- - - - - - - - - - 
- - - - - - - - - - 
}

Additional Resources

For readers who want to dive deeper into Swagger and OpenAPI, here are some valuable resources:

• Swagger Official Documentation
• OpenAPI Specification(version 3.1.0)
• Springdoc OpenAPI
• Postman vs. Swagger

These are some of the resources I referred to. If you have any questions or corrections, please let me know in the comments section.