Home/ Questions/Q 2380

Querify Question Shop: Explore Expert Solutions and Unique Q&A Merchandise Latest Questions

Author
  • 61k
Asked: 2024-11-26T04:52:06+00:00

Swagger Made Simple: A Walkthrough of API Documentation

  • 61k

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.

This diagram illustrates the 8 essential building blocks of an OpenAPI specification. It categorizes the fundamental elements needed to define a RESTful API clearly and effectively

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.

The image showcases Swagger UI, a web-based tool that dynamically generates interactive API documentation.

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.

Swagger Editor, a web-based tool where you can write and edit API specifications in YAML or JSON format.

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>
Enter fullscreen mode Exit fullscreen mode

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();     }
Enter fullscreen mode Exit fullscreen mode

This image displays an example of a GET request to the /employee endpoint. The operation is documented with a summary (

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);     } }
Enter fullscreen mode Exit fullscreen mode

This image shows a DELETE request for /employee/{id} that deletes a specific employee. The responses include 200 (Employee Deleted) and 404 (Employee not found).

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); }
Enter fullscreen mode Exit fullscreen mode

This image shows a GET request for /employee/{id}, with a description for the required path variable id, which is the ID of the employee to be retrieved

4. @Tag

Used to group related operations in the documentation. 

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

This image shows a list of requests grouped under a common @Tag annotation.

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.

apibeginnersspringbootwebdev
Share

Leave an answer

You must login to add an answer.

Need An Account,