Swagger/OpenAPI Generation for Java: Tools Overview |…

Swagger/OpenAPI Generation for Java: A Complete Overview of Tools and Libraries

Modern REST API development in Java is unthinkable without high-quality documentation. The OpenAPI standard (formerly known as the Swagger Specification) has become the de facto industry standard for describing HTTP APIs. In this article, we will thoroughly examine the main libraries and tools for generating OpenAPI specifications in Java applications, their capabilities, usage examples, and selection criteria.

What is OpenAPI and why is it needed?

OpenAPI is a specification that describes a RESTful API in JSON or YAML format. It includes:

a list of endpoints and HTTP methods;
data models (request and response schemas);
parameters (query, path, header);
authentication and authorization information.

Documentation generated from OpenAPI allows you to automatically create client SDKs, conduct testing, and keep the API description up to date. For Java, there are several mature solutions.

1. SpringDoc OpenAPI (recommended for Spring Boot)

SpringDoc is the most popular library for generating OpenAPI 3 in the Spring ecosystem. It automatically scans controllers, annotations like @RequestMapping, @GetMapping, etc., and builds the specification based on them.

Setup (Maven)

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

Example controller with annotations

@RestController@RequestMapping("/api/users")public class UserController {

    @Operation(summary = "Get user by ID")    @ApiResponses(value = {        @ApiResponse(responseCode = "200", description = "User found"),        @ApiResponse(responseCode = "404", description = "User not found")    })    @GetMapping("/{id}")    public ResponseEntity<User> getUser(@PathVariable Long id) {        // logic        return ResponseEntity.ok(new User(id, "Ivan", "ivan@example.com"));    }}

After starting the application, the documentation is available at /swagger-ui.html, and the JSON specification at /v3/api-docs.

2. Swagger Core (OpenAPI 3.0)

Swagger Core is a low-level library from the creators of the specification. It allows you to programmatically build OpenAPI objects and serialize them to JSON/YAML. It is suitable for cases where fine-grained control over generation is needed.

Example of programmatic specification creation

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

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Example API")        .version("1.0.0")        .description("Manually created documentation"))    .path("/hello", new PathItem()        .get(new Operation()            .summary("Greeting")            .operationId("sayHello")            .addParametersItem(new Parameter()                .name("name")                .in("query")                .required(false)                .schema(new StringSchema()))            .responses(new ApiResponses()                .addApiResponse("200", new ApiResponse()                    .description("OK")                    .content(new Content()                        .addMediaType("text/plain",                             new MediaType().schema(new StringSchema())))))));

// Serialization to JSONObjectMapper mapper = new ObjectMapper();String json = mapper.writeValueAsString(openAPI);System.out.println(json);