OpenAPI and Swagger

OpenAPI and Swagger

OpenAPI (formerly Swagger) is a specification for describing REST APIs. It provides a machine-readable contract that tools can use for documentation, client generation, and testing.

Why OpenAPI Matters

An OpenAPI spec describes every endpoint, request body, response, and error code in your API. Tools like Swagger UI render interactive documentation. Code generators create client libraries in dozens of languages.

SpringDoc OpenAPI

SpringDoc automatically generates an OpenAPI 3.0 spec from your Spring controllers. Add the dependency and you get documentation for free:

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

Visit http://localhost:8080/swagger-ui.html and you see interactive documentation for every endpoint.

Adding Metadata

Enrich your API documentation with annotations:

@Operation(summary = "Get a product by ID",
           description = "Returns a single product or throws 404")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "Product found"),
    @ApiResponse(responseCode = "404", description = "Product not found")
})
@GetMapping("/{id}")
public Product getById(@PathVariable Long id) {
    return productService.findById(id)
        .orElseThrow(() -> new ResourceNotFoundException("Not found"));
}

OpenAPI Configuration

Configure your API metadata in a bean:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Product API")
            .version("1.0")
            .description("REST API for managing products"));
}

Client Generation

The OpenAPI Generator tool creates typed client code from your spec. Run it with the spec URL and target language:

openapi-generator generate 
  -i http://localhost:8080/v3/api-docs 
  -g java 
  -o ./generated-client

Key Points

• OpenAPI provides a machine-readable contract for REST APIs.
• SpringDoc generates OpenAPI specs automatically from Spring controllers.
• Swagger UI renders interactive API documentation.
• Use @Operation and @ApiResponse to enrich endpoint metadata.
• OpenAPI Generator creates typed client libraries in many languages.