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.

. You can understand it better by interacting with it.

3. Swagger Codegen

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 . 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 :

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();

    }

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);

}

Additional Resources

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

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