OpenAPI / Swagger Java: Methods, Examples, Installation |…

What is OpenAPI / Swagger and why does a Java developer need it?

\n\n

OpenAPI (formerly known as Swagger) is a specification for describing, creating, documenting, and consuming RESTful APIs. For a Java developer, OpenAPI / Swagger libraries are an indispensable tool that automates the process of API documentation and client code generation.

\n\n

Main reasons to use OpenAPI / Swagger in Java projects:

Automatic documentation generation — the library analyzes your code (Spring Boot annotations, JAX-RS) and creates interactive documentation in Swagger UI format.
Standardization — a unified API description format understandable to both humans and machines.
Client code generation — you can generate a Java client for any API described in OpenAPI.
Testing — Swagger UI allows you to make requests to the API directly from the browser.
CI/CD integration — you can verify API compliance with the specification at the build stage.

\n\n

In this article, we will look at two main Java libraries: springdoc-openapi (for Spring Boot) and Swagger Core (for JAX-RS and other frameworks).

\n\n

Installing the OpenAPI / Swagger library for Java

\n\n

Installation depends on the framework used. Let's look at two main options.

\n\n

Option 1: Spring Boot (springdoc-openapi)

Add the dependency to your pom.xml (Maven):

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

\n\n

For Gradle (build.gradle):

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

\n\n

Option 2: JAX-RS / Jakarta (Swagger Core)

Maven:

<dependency>\n    <groupId>io.swagger.core.v3</groupId>\n    <artifactId>swagger-jaxrs2-jakarta</artifactId>\n    <version>2.2.22</version>\n</dependency>

\n\n

Gradle:

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

\n\n

Quick start: first example with Spring Boot

\n\n

After adding the springdoc-openapi dependency to a Spring Boot project, Swagger UI is automatically available at http://localhost:8080/swagger-ui.html. Let's create a simple controller:

\n\n

import io.swagger.v3.oas.annotations.Operation;\nimport io.swagger.v3.oas.annotations.tags.Tag;\nimport org.springframework.web.bind.annotation.*;\n\n@RestController\n@RequestMapping("/api/users")\n@Tag(name = "User Controller", description = "User management")\npublic class UserController {\n\n    @GetMapping("/{id}")\n    @Operation(summary = "Get user by ID")\n    public String getUser(@PathVariable Long id) {\n        return "User with ID: " + id;\n    }\n\n    @PostMapping\n    @Operation(summary = "Create a new user")\n    public String createUser(@RequestBody String userName) {\n        return "Created user: " + userName;\n    }\n}

\n\n

After starting the application, open http://localhost:8080/swagger-ui.html — you will see interactive documentation with the ability to make requests.

\n\n