Swagger/OpenAPI Generation for Java: Best Libraries

Swagger/OpenAPI Generation for Java: A Complete Guide to Tools

In modern Java development, creating high-quality API documentation has become an integral part of the process. The OpenAPI specification (formerly known as Swagger) provides a standardized format for describing RESTful APIs. In this article, we will review the main tools for generating Swagger/OpenAPI documentation in Java projects, their features, and usage examples.

What are Swagger and OpenAPI?

Swagger is a set of tools for designing, building, and documenting REST APIs. OpenAPI is a specification that defines the standard for API description. Swagger is the most popular implementation of this specification.

Main Libraries for Java

Let's look at three key tools:

• SpringDoc OpenAPI — a modern library for Spring Boot
• Swagger Core — the base library from the creators of Swagger
• OpenAPI Generator — a tool for generating code and documentation

1. SpringDoc OpenAPI

SpringDoc is the most popular choice for Spring Boot projects. It automatically integrates with your application and generates documentation based on annotations and data types.

Installation and Configuration

Add the dependency to pom.xml:

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

Usage Example

Create a simple controller with documentation:

@RestController@RequestMapping("/api/users")@Tag(name = "Users", description = "User management")public class UserController {

    @GetMapping("/{id}")    @Operation(summary = "Get user by ID")    public ResponseEntity<User> getUser(            @Parameter(description = "User ID")            @PathVariable Long id) {        // implementation        return ResponseEntity.ok(new User(id, "Ivan"));    }

    @PostMapping    @Operation(summary = "Create a new user")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // implementation        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

After starting the application, the documentation will be available at http://localhost:8080/swagger-ui.html.

2. Swagger Core

The Swagger Core library provides a lower-level approach to creating the OpenAPI specification. It is suitable for projects where full control over generation is required.

Example of Manual Specification Creation

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Pet Store API")        .description("API for managing pets")        .version("1.0.0")        .contact(new Contact()            .name("Developer")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("Production server"));

// Adding paths and componentsPaths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("Get list of pets")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator is a tool that can generate both documentation and client/server code based on the OpenAPI specification.

Usage in Maven

Add the plugin to pom.