Introduction to Swagger

Swagger is a set of open-source software tools designed to help developers design, build, document, and consume RESTful web services. Its main goal is to simplify the development and documentation of APIs (Application Programming Interface) to make them more accessible and easier to understand for developers.

What is Swagger?

Swagger provides a standard specification for describing RESTful APIs. This specification, known as the OpenAPI Specification (OAS), allows developers to clearly and precisely describe API endpoints, available HTTP methods (GET, POST, PUT, DELETE, etc.), input and output parameters, and data types used.

Main Components of Swagger

1. Swagger Editor: An online editing tool that allows developers to create and edit API specifications in YAML or JSON format.
2. Swagger UI: An interactive graphical interface that generates visual documentation of APIs from an OpenAPI specification. Developers can test API calls directly from the generated documentation, facilitating understanding and use of the API.
3. Swagger Codegen: A tool that allows generating client and server code in various programming languages from an OpenAPI specification.
4. Swagger Hub: A collaborative platform that enables development teams to work together on designing, documenting, and maintaining their APIs.

How Swagger Works

1. API Design: Developers start by creating an OpenAPI specification in YAML or JSON format. This specification describes all API details, including endpoints, methods, parameters, response schemas, and more.
2. Documentation: Once the specification is created, Swagger UI can be used to generate interactive and visual documentation. This documentation allows users to explore and test API endpoints directly from the browser.
3. Code Generation: With Swagger Codegen, developers can automatically generate clients and servers in various programming languages based on the API specification. This facilitates API implementation and consumption in different environments.
4. Collaboration: Using Swagger Hub, development teams can work together on the API specification, reviewing changes, providing feedback, and ensuring the API meets established requirements and standards.

How to Install Swagger with the Latest Version in Spring Boot

Step 1: Understand the differences:

Before performing the update, it is crucial to review the release notes and documentation to understand the differences between the version you have and the latest one.

Step 2: Update the pom.xml file:

Make sure you have the correct dependency defined for Swagger 3.0 in your project's dependencies block. For this, we will add the following library to our pom.xml file:

This is a library to integrate Swagger UI with Spring Boot, which will allow generating the necessary documentation for OpenAPI.

• groupId: is the group identifier to which the library belongs in the Maven repository, in this case, it belongs to the group “org.springdoc“
• ArtifactId: is the unique identifier of the library within the group, in this case, the library is called springdoc-openapi-ui.
• Version: here we specify the version you will use in the project, in this case, it would be version 1.6.15

Step 3: Remove the SpringFox library

In the pom.xml file, we will remove the library:

This library will be removed because it uses versions prior to Swagger 3.0; for our new version, we will use the libraries mentioned in step 2.

Step 4: Remove the SwaggerConfig file                                                                                                                          This file is located inside src/main/java/config.java.

Step 5: Add code to Configure and define OpenAPI

Navigate to src/main/java/ and look for the file named MicroserviceNameOfMicro or microNameOfMicro and add the following lines of code.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.servers.Server;

@OpenAPIDefinition(info = @Info(title = "Microservice nameMS",
version = "1.0.3",
description = "APIs Swagger Microservice nameMS",
license = @License(name = "Apache 2.0",
contact = @Contact(url = "S", name = "MS-nameMS", email = "")),
security = {@SecurityRequirement(name = "") },
servers = {
@Server(description = "local environment", url = "http://localhost:8080/"),
@Server(description = "dev environment URL exposed by Apigateway", url = ""),
@Server(description = "qa environment URL exposed by Apigateway", url = "https://"),
@Server(description = "prod environment URL exposed by Apigateway", url = "https:/")

}
)
@SpringBootApplication
@EnableAsync
@EnableConfigurationProperties({ApplicationProperties.class})
public class NameMS{

	public static void main(String[] args) {
		SpringApplication.run(NameMS.class, args);
	}

}

This code is used in the configuration and defines the API documentation based on OpenAPI. Below is an explanation of the different parts of the annotations and their purpose:

@OpenAPIDefinition: This annotation is placed on the main class and is used to define general API information. It contains the following parameters:

• info: Here you provide API information such as your Microservice title, version, and description.
• license: Allows specifying the license under which the API is distributed, such as the ‘name’ and a ‘url’ for more details.
• contact: Here you provide information about the team, where in the url you will include information about the microservice you are working on.

Step 6: Add code in Application.yaml

openapi:
  expand:
    api:
      version: v1.1

Step 7: Add details to the controller interface.

Annotations:

• @Operation → Endpoint name, its description, and also the name of the microservice.
• @Parameter → Input parameters for the endpoint. The name must match the one used in the endpoint (Example: if the endpoint is → /{id}/→ the name should be name = “id“).
• @ApiResponses → Here you specify the responses implemented in the controller. If there is a response that returns 200 but comes empty, here it should be left as 204 with the description indicated in the code, since some cases require that even if no data is returned, a correct response is shown but without data.

Example of how it should be done:

package cl.microservicio.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

public interface Controller {
    @Operation(summary = "...", description = "Endpoint that fetches the request data", tags={ "name of your microservice" }	)
    @Parameter(name = "id", description = "", example = "", required = true)
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Query Successfully Generated."),
        @ApiResponse(responseCode = "204", description = "No data found for the queried id."),
        @ApiResponse(responseCode = "500", description = "Error in the query")
    })

}

To verify that everything is correct, you must run the microservice locally and open the following URL in your browser: http://localhost:8080/swagger-ui/index.html# . If everything is fine, you will be able to see the description of your endpoints.

FINAL STEP:

In the previously opened link, you will find in the upper left corner the link marked in red, which will open a JSON in a new tab that must be converted to YAML format (you can use the following link: JSON to YAML Converter Online Tool  and what is generated must be saved in a new file located at the root of the microservice called swagger.yaml

‍

Advantages of Using Swagger

• Open Standard: Swagger uses the OpenAPI specification, a widely accepted open standard for describing RESTful APIs.
• Clear Documentation: It provides interactive and easy-to-understand documentation, making it easier for developers and users to understand how to interact with the API.
• Productivity: Automatic generation of client and server code saves time and reduces errors, allowing developers to focus on business logic.
• Collaboration: It facilitates collaboration among development teams, ensuring all members work with a clear and consistent view of the API.

In summary, Swagger is a powerful tool that facilitates the design, documentation, and consumption of RESTful APIs, improving productivity and collaboration in development teams.

Ready to improve the documentation and testing of your RESTful APIs?

At Kranio, we have experts in backend development and API documentation who will help you implement efficient solutions using Swagger and Spring Boot, ensuring your services are easily understandable and testable. Contact us and discover how we can boost the quality and efficiency of your developments.