Intro 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 objective is to simplify API (Application Programming Interface) development and documentation 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 the endpoints of the API, the available HTTP methods (GET, POST, PUT, DELETE, etc.), the input and output parameters, the types of data used.

Swagger Core Components

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 API documentation based on an OpenAPI specification. Developers can test API calls directly from the generated documentation, making it easier to understand and use the API.
3. Swagger Codegen: A tool that allows you to generate client and server code in several programming languages based on an OpenAPI specification.
4. Swagger Hub: A collaborative platform that allows development teams to work together on the design, documentation and maintenance of their APIs.

How Swagger Works

1. API design: Developers start by creating an OpenAPI specification in YAML or JSON format. This specification describes all the details of the API, including endpoints, methods, parameters, response schemes, and more.
2. Documentation: Once the specification has been 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 makes it easier to implement and consume the API in different environments.
4. Collaboration: Using Swagger Hub, development teams can work together on the API specification, reviewing changes, providing feedback, and ensuring that the API meets established requirements and standards.

How to install Swagger with the latest version in Spring boot

Step 1: Understand the differences:

Before upgrading, it's crucial to review the release notes and documentation to understand the differences between your current version and the latest version.

Step 2: Update the pom.yaml file:

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

This is a library for integrating Swagger UI with spring boot, which will allow us to generate the necessary documentation for OpenAPI.

• GroupID: is the identifier of the group to which the library belongs in the Maven repository, in this case it belongs to the “org.springdoc” group
• 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 delete the library:

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

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

Step 5: Add code to Configure and Define OpenAPI

We will locate src/main/java/ we will look for the file that says MicroserviceName of the Micro or My Name of the Micro and we will 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 = "Microservicio nameMS",
version = "1.0.3",
description = "APIs Swagger Microservicio nameMS",
license = @License(name = "Apache 2.0",
contact = @Contact(url = "S", name = "MS-nameMS", email = "")),
security = {@SecurityRequirement(name = "") },
servers = {
@Server(description = "ambiente local", url = "http://localhost:8080/"),
@Server(description = "url ambiente dev expuesta por Apigateway", url = ""),
@Server(description = "url ambiente qa expuesta por Apigateway", url = "https://"),
@Server(description = "url ambiente prod expuesta por 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 documentation of the OpenAPI-based API, then the different parts of the annotations and their purpose will be explained:

@OpenAPIDefinition: This annotation is placed in the main class, it is used to define the general information of the API, it contains the following parameters:

• info: API information is provided here, such as the title of your Microservice, version, and description.
• License: It allows you to specify the license to which the API is distributed, such as the 'name' and a 'url' for more details.
• Contact: Here we will provide information about the team, where in the URL we will include the information of the microservice we 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 → Name of the endpoint, description of the endpoint and also the name of the microservice.
• @Parameter → Input parameters for the endpoint. In the name it must have the same name as in the endpoint (Example: in the endpoint it is like this →/{id} /→ in the name it must say name = “id “).
• @ApiResponses → Here are the answers you have in the controller implementation. If there is an answer that answers 200 but comes empty here, you have to leave it as 204 and with the description indicated in the code, since some cases ask that even if there is no data, a correct answer must be 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 que trae los datos de la solicitud", tags={ "nombre de tu microservicio" }	)
    @Parameter(name = "id", description = "", example = "", required = true)
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Consulta Generada Correctamente."),
        @ApiResponse(responseCode = "204", description = "No se han encontrado datos para el id consultado."),
        @ApiResponse(responseCode = "500", description = "Error en la consulta")
    })

}

To verify that everything is fine, we must turn up the microservice locally and in the browser open the following url: http://localhost:8080/swagger-ui/index.html # . If all is well, you'll be able to see the description of your endpoints.

LAST 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 transformed to the YAML format (you can use the following link: Online JSON to YAML Converter Tool And whatever is generated you must save it in a new file located at the root of the microservice called swagger.yaml

‍

Benefits of Using Swagger

• Open Standard: Swagger uses the OpenAPI specification, a widely accepted open standard for describing RESTful APIs.
• Clear Documentation: 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: Facilitates collaboration between development teams, ensuring that all members work with a clear and consistent vision of the API.

In short, 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 that your services are easily understandable and probable. Contact us and discover how we can boost the quality and efficiency of your developments.