Introduction

If you already have a Spring REST API, you usually do not need to hand-write the first OpenAPI document from scratch. The typical approach is to add a library that inspects your controllers, request mappings, and model types, then exposes the generated OpenAPI 3 description as JSON or YAML.

Use springdoc-openapi for Existing Spring APIs

For modern Spring Boot applications, springdoc-openapi is the usual choice. Add the starter dependency and let it scan your application at runtime.

For Maven:

1<dependency>
2    <groupId>org.springdoc</groupId>
3    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
4    <version>2.6.0</version>
5</dependency>

For Gradle:

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

Once the app starts, springdoc generates the OpenAPI document automatically from your existing endpoints.

Fetch the Generated YAML

After you start the application, the generated spec is typically available at:

• '/v3/api-docs for JSON'
• '/v3/api-docs.yaml for YAML'

You can retrieve the YAML directly:

curl http://localhost:8080/v3/api-docs.yaml -o openapi.yaml

That gives you a real OpenAPI 3 document based on the live Spring configuration, not a manually synced copy that can drift from the code.

A Minimal Spring Example

The generation works best when your controllers already express request and response structure clearly.

1@RestController
2@RequestMapping("/books")
3public class BookController {
4
5    @GetMapping("/{id}")
6    public ResponseEntity<BookDto> getBook(@PathVariable Long id) {
7        return ResponseEntity.ok(new BookDto(id, "Distributed Systems"));
8    }
9
10    @PostMapping
11    public ResponseEntity<BookDto> createBook(@RequestBody CreateBookRequest request) {
12        BookDto created = new BookDto(42L, request.title());
13        return ResponseEntity.status(HttpStatus.CREATED).body(created);
14    }
15}

From this, springdoc can infer paths, methods, request bodies, and many schema details automatically.

Improve the Generated Spec With Annotations

Automatic generation gets you a solid baseline, but production-quality docs often need extra metadata. Add annotations where the defaults are too vague.

1@Operation(summary = "Get a book by id")
2@ApiResponses({
3    @ApiResponse(responseCode = "200", description = "Book found"),
4    @ApiResponse(responseCode = "404", description = "Book not found")
5})
6@GetMapping("/{id}")
7public ResponseEntity<BookDto> getBook(@PathVariable Long id) {
8    return ResponseEntity.ok(new BookDto(id, "Distributed Systems"));
9}

This improves the resulting YAML without forcing you to maintain a separate source of truth for the whole API.

Add Top-Level API Metadata

You can also customize the generated document with an OpenAPI bean:

1@Bean
2public OpenAPI apiInfo() {
3    return new OpenAPI()
4        .info(new Info()
5            .title("Book Service API")
6            .version("v1")
7            .description("Public REST API for book operations"));
8}

This helps turn a technically correct specification into one that is actually useful to consumers.

Generate a File as Part of the Build

If you want a checked-in YAML file or an artifact generated in CI, call the docs endpoint during the build or test pipeline after starting the app. Teams often:

1. Start the Spring Boot app in CI
2. Request /v3/api-docs.yaml
3. Save the result as openapi.yaml
4. Publish it or compare it in validation steps

That approach keeps the specification synchronized with the running codebase. It also gives downstream tooling a stable artifact for client generation, review, or contract testing without forcing developers to update YAML by hand.

Common Pitfalls

• Expecting perfect docs without annotations can be disappointing when controller signatures do not communicate enough detail.
• Forgetting to include the springdoc dependency means /v3/api-docs.yaml simply will not exist.
• Complex generic wrappers and custom serializers can produce schemas that need manual annotation help.
• Treating a generated YAML file as permanent static documentation leads to drift if it is not refreshed regularly.

Summary

• Add springdoc-openapi to an existing Spring application to generate an OpenAPI 3 specification automatically.
• Fetch the YAML from /v3/api-docs.yaml.
• Use annotations and top-level metadata to improve the output.
• In CI, generate the YAML from the running app so the specification stays aligned with the code.