Skip to main content

One post tagged with "Swagger"

View All Tags

· 3 min read

Do you want to know what's in a REST API without having to ask? Ask no more! Swagger is here to help, and it is an effective tool for describing RESTful APIs. In this article, I will provide a simple implementation that you can use in your Spring Boot application to make it more effective. I’m writing this article because I struggled to find a straightforward method that effectively communicates the implementation details.

GitHub Repository Example​

For a practical example, check out the GitHub repository: Spring Boot 3 OpenAPI Swagger Example.

What We Will Build​

We'll build a simple Products REST API that sources data from a service class. You can easily extend this to use your own data source. The focus will be on integrating Swagger to document the API endpoints.

Getting Started​

You can generate a standard Spring Boot application using Spring Initializr. Alternatively, start with the pre-configured Git repository mentioned above.

Step 1 of 3: Dependencies​

Add the following dependency to your pom.xml:

<properties>
  <springdoc.version>2.1.0</springdoc.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>${springdoc.version}</version>
  </dependency>
</dependencies>

Step 2 of 3: Configuration​

Update your application.properties:

# SpringDoc Configuration
springdoc.api-docs.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.try-it-out-enabled=true

# Server Configuration
server.port=8088
server.servlet.context-path=/api

Optional Swagger Configuration (SwaggerConfig.java)​

To customize your Swagger documentation, use this configuration:

package com.springboot.example.docs.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.servers.Server;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI(@Value("${server.port}") String serverPort,
                                 @Value("${server.servlet.context-path}") String contextPath) {

        Info info = new Info()
            .title("Products API")
            .version("1.0.0")
            .description("API documentation for managing products.")
            .termsOfService("http://swagger.io/terms/")
            .contact(new Contact()
                .name("DevSecOps Team")
                .url("http://devsecops.com/contact")
                .email("[email protected]"))
            .license(new License()
                .name("Apache 2.0")
                .url("http://www.apache.org/licenses/LICENSE-2.0.html"));

        Server server = new Server()
            .url(String.format("http://localhost:%s%s", serverPort, contextPath))
            .description("Development Server");

        return new OpenAPI().info(info).addServersItem(server);
    }
}

Step 3 of 3: Creating Your REST API​

Here's a basic ProductsController to demonstrate API documentation with Swagger:

@RestController
@RequestMapping("/products")
public class ProductsController {

    private final ProductService productService;

    public ProductsController(ProductService productService) {
        this.productService = productService;
    }

    @Operation(summary = "Get all products")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Successfully retrieved list of products"),
        @ApiResponse(responseCode = "500", description = "Internal server error")
    })
    @GetMapping
    public ResponseEntity<List<Product>> getAllProducts() {
        return new ResponseEntity<>(productService.getAllProducts(), HttpStatus.OK);
    }

    // Other CRUD operations follow similar patterns...
}

Good to Go: Launching the Swagger UI​

Run your application and open your browser to:

http://localhost:8088/api/swagger-ui/index.html

to see the Swagger documentation in action.

Conclusion​

By integrating Swagger with Spring Boot 3, you've made your REST API more accessible, understandable, and easier to test. This setup provides a quick way to onboard team members and stakeholders with a comprehensive API view.

Stay tuned for the next article, where we'll dive deeper into building a CRUD REST API with Spring Boot 3 and JPA!