OpenAPI, Swagger and Spring Boot REST APIs

By

Building web services and documenting RESTful endpoints is no easy task, but testing RESTful APIs has always been a particularly sore point with Spring Boot and Java.

Sure, you can test a GET invocation in a web browser, but if you want to test a PUT or POST method you either must fight with cURL or install a product such as Postman Desktop.

Swagger UI and RESTful Java APIs

However, if you add Swagger to a Spring Boot or Java project, a variety of OpenAPI 3.0-compliant features become available to you. For Java developers, the web UI that enables testing of RESTful APIs is of particular interest.

The web UI is available by adding the SpringDoc OpenAPI starter to your Gradle or Maven file. This provides a web-based interface that makes it easy to test the following:

  • HTTP methods such as GET, POST, PUT and PATH.
  • Query parameters (@RequestParams in Spring Boot).
  • Path parameters (@PathVariables in Spring Boot).
  • RESTful Spring Boot APIs that return JSON.
  • Java API clients that consume XML.
Screenshot of the Spring Boot OpenAPI Swagger UI.
You can easily test REST APIs after you add OpenAPI's Swagger to Spring Boot applications.

How to add Swagger to Spring Boot

To add the OpenAPI 3.0-compliant version of Swagger to a Spring Boot app, follow these steps:

  1. Copy the SpringDoc OpenAPI WebMVC project's Maven or Gradle coordinates from a public Maven repository.
  2. Update your Maven POM file or your Gradle build file with the copied dependency.
  3. Rebuild and redeploy your Swagger-enabled Spring Boot REST application.
  4. Access the Spring Boot Swagger UI at the following URL: http://localhost:8080/swagger-ui
  5. Actively test your RESTful Java API with the friendly Swagger user interface.

The following code shows the coordinates for the SpringDoc OpenAPI Maven dependency for Swagger and Spring Boot:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

OpenAPI Spring Boot tools

As a developer, the ability to use Swagger to test Spring Boot APIs in the browser without having to install an additional tool makes my life significantly easier.

However, the OpenAPI 3.0 Java annotations simplify the documentation of REST APIs, and the REST schema generation tools are also incredibly helpful. The Swagger tools simplify all of Spring Boot's RESTful API development lifecycle.

This code shows SpringDoc's WebMVC Gradle dependency for OpenAPI Spring Boot integration:

implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.6.0'

OpenAPI, Swagger and SmartBear

Swagger is managed and maintained by SmartBear Software, which acquired the technology in 2015 and donated the spec to the OpenAPI Initiative under the Linux Foundation. The OpenAPI Specification, which is used to define HTTP API structure and syntax, is built through a community consensus and is Apache 2.0 Licensed.

SmartBear continues to use the Swagger brand for its own products, including a Swagger UI tool that implements the OpenAPI (OAS) spec.

Cameron McKenzie has been a Java architect for over 20 years. His current specialties include AI development with Docker, Spring Boot, the Modular platform for AI and the Mojo programming language.

View All Videos