Spring Boot 4 Microservices & REST APIs · Lesson

Customizing the OpenAPI Spec

Add metadata, servers, and security schemes.

Customizing the OpenAPI Spec is a free Spring Boot 4 Microservices & REST APIs lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Microservices & REST APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Customizing the whole spec

Beyond per-endpoint annotations, you can shape the entire document - title, version, contact, license, servers and security - by defining an OpenAPI bean.

Defining an OpenAPI bean

Return an OpenAPI object from a @Bean method and SpringDoc uses it as the base document.

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                .title("Orders API")
                .version("v1")
                .description("Public ordering service"));
}

The info section

The Info object holds metadata shown at the top of Swagger UI: title, version, description, terms of service, contact and license.

new Info()
    .title("Orders API")
    .version("1.2.0")
    .contact(new Contact().name("API Team").email("api@acme.com"))
    .license(new License().name("Apache 2.0").url("https://apache.org/licenses/LICENSE-2.0"));

Declaring servers

List the base URLs where the API is reachable. Swagger UI lets users pick a server, and generated clients use these as base paths.

new OpenAPI()
    .addServersItem(new Server().url("https://api.acme.com").description("Production"))
    .addServersItem(new Server().url("http://localhost:8080").description("Local"));

Why servers matter behind a proxy

When your app sits behind a gateway or context path, the auto-detected server URL can be wrong. Declaring servers explicitly ensures "Try it out" calls hit the correct address.

Security schemes

Document how clients authenticate by registering a SecurityScheme in the components, e.g. a bearer JWT.

new OpenAPI()
    .components(new Components()
        .addSecuritySchemes("bearerAuth",
            new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")));

Applying security globally

Add a SecurityRequirement so the UI shows a lock icon and lets users supply a token for all secured operations.

new OpenAPI()
    .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
    .components(/* scheme defined above */);

Per-operation security

To secure only some endpoints, use @SecurityRequirement on the controller method instead of declaring it globally.

@SecurityRequirement(name = "bearerAuth")
@GetMapping("/admin/stats")
public Stats stats() { ... }

Grouping APIs with GroupedOpenApi

For large apps you can split docs into named groups (e.g. public vs admin) using GroupedOpenApi, each with its own path matchers.

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/public/**")
            .build();
}

Customizing via properties

Some settings can be done without code through springdoc.* properties - sorting operations, packages to scan, and which paths to include.

# application.yml
springdoc:
  packages-to-scan: com.acme.api
  paths-to-match: /api/**
  swagger-ui:
    operations-sorter: method

OpenApiCustomizer for fine control

For programmatic tweaks to every operation, implement an OpenApiCustomizer bean and mutate the document after generation - e.g. add a common header to all paths.

Quick Check

Test your spec-customization understanding.

Recap

You customized the whole document:

An OpenAPI bean sets Info, servers and security
Declare servers for proxies/context paths
SecurityScheme + SecurityRequirement document auth
GroupedOpenApi splits large APIs

Frequently asked questions

Is the “Customizing the OpenAPI Spec” lesson free?

Yes — the full text of “Customizing the OpenAPI Spec” is free to read here on the web, and the Spring Boot 4 Microservices & REST APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Microservices & REST APIs course, upgrade to CoddyKit PRO.

What will I learn in “Customizing the OpenAPI Spec”?

Add metadata, servers, and security schemes. You practise Spring Boot 4 Microservices & REST APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Microservices & REST APIs?

No prior experience is required. Spring Boot 4 Microservices & REST APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Customizing the OpenAPI Spec” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Microservices & REST APIs lesson?

Yes. Every Spring Boot 4 Microservices & REST APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Spring Boot 4 Microservices & REST APIs