Springdoc openapi starter webmvc ui: Quick Setup and Secure API Docs

If you’ve ever dreaded the thought of manually creating and maintaining API documentation, you’re in the right place. The springdoc-openapi-starter-webmvc-ui library is a game-changer for Spring Boot developers, transforming what used to be a tedious chore into an almost effortless, ‘zero-config’ experience.

At its core, Springdoc inspects your existing REST controllers, figures out your endpoints, and automatically generates a beautiful, interactive Swagger UI. This means you can go from raw code to a fully documented and testable API in just a few minutes.

Your First Steps With Springdoc And Swagger UI

Let’s dive right in and see how easy it is to get this up and running. We’ll start by adding a single dependency to a basic Spring Boot application and watch the magic happen.

Adding The Dependency

First things first, you need to tell your build system about Springdoc. Whether you’re a Maven or Gradle user, this just means adding one line to your build file. This single dependency is the key that unlocks all of Springdoc’s auto-configuration power.

Quick-Start Dependencies For Maven And Gradle

Here is the exact dependency snippet you need to add to your build file. Just copy and paste the one for your build system to get started.

Build System	Dependency Snippet
Maven	<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.8.6</version> </dependency>
Gradle	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6'

Just be sure you’re using the correct starter. The webmvc version is for standard, servlet-based Spring Boot apps. If you were building a reactive application with WebFlux, you’d use the webflux alternative instead. If you ever run into conflicts, remember you can always inspect the project’s dependency hierarchy. For a deeper look, check out our guide on understanding the Maven dependency tree.

Building A Simple API

With the dependency in place, let’s create a minimal REST controller to give Springdoc something to document. We’ll add a simple GET endpoint that returns a greeting.

Create a new Java class named GreetingController inside your controller package. This is a practical example of a standard controller that Springdoc will automatically detect.

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

    @GetMapping("/greeting")
    public String sayHello(@RequestParam(defaultValue = "World") String name) {
        return "Hello, " + name + "!";
    }
}

Notice that this is just a standard Spring @RestController. There’s nothing specific to Springdoc in the code itself. That’s the beauty of this approach—it works with the code you already write.

This simple flow is all it takes to turn your code into interactive documentation.

As the diagram shows, once you add the dependency, Springdoc handles the heavy lifting of turning your API code into browsable, functional docs.

Viewing Your First Swagger UI

Now for the payoff. Run your Spring Boot application. Once it’s up, open your web browser and navigate to http://localhost:8080/swagger-ui.html.

You should be greeted by the Swagger UI interface, which has automatically discovered and documented your /greeting endpoint. You’ll see the path, the HTTP method (GET), and the request parameter (name). You can even use the “Try it out” button to execute the API call directly from your browser. For instance, entering “Developer” into the name field and clicking “Execute” will show you the exact curl command (curl -X GET "http://localhost:8080/greeting?name=Developer") and the server response (Hello, Developer!).

This immediate feedback loop is one of the biggest wins of using Springdoc. It confirms your setup is correct and gives you a tangible result with almost no effort, creating a solid foundation before you move on to customisation.

This ease of use has led to widespread adoption. In the French public sector, for instance, the use of springdoc-openapi-starter-webmvc-ui surged by over 150% between 2023 and 2025. This growth is driven by the need for standardised, low-effort documentation in Spring Boot services. As of early 2026, at least eight major INSEE projects actively depend on this library, covering about 25% of their surveyed Spring-based repositories. You can explore its popularity and available versions on the Maven Repository.

Bringing Your API Documentation To Life With Annotations

While springdoc-openapi-starter-webmvc-ui gives you an incredible head start with its “zero-config” approach, the initial result is really just a skeleton. It knows what your endpoints are, but it has no idea about their purpose, context, or the story behind them.

This is where you, as the developer, step in. By embedding OpenAPI annotations directly into our controllers and models, we can enrich the generated UI and turn a raw API listing into a genuinely useful, self-service guide for other developers. Let’s walk through this with a practical product catalogue API to see just how effective it can be.

Describing Endpoints With @Operation

The most fundamental annotation you’ll use is @Operation. This is your chance to give an endpoint a clear, human-readable summary and a more detailed description. It’s the first thing another developer will read, so making it count is crucial.

Think about a standard ProductController. Without any help, an endpoint like GET /products/{id} is pretty ambiguous. Does it return the whole product object? A lightweight summary? The @Operation annotation clears this up immediately.

Here is a practical example of adding it to a method in our ProductController:

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Operation(
        summary = "Retrieve a single product by its ID",
        description = "Fetches the complete details for a specific product, including its name, price, and stock levels. Returns a 404 error if the product is not found."
    )
    @GetMapping("/{id}")
    public Product getProductById(@PathVariable Long id) {
        // ... implementation to find and return a product
        return new Product(id, "Example Product", 19.99, 100);
    }

    // ... other endpoints
}

Just like that, our endpoint in the Swagger UI is no longer a mystery. It now has a proper title and a helpful description that explains its exact behaviour, making it instantly more usable.

Detailing Parameters And Responses

Knowing what an endpoint does is only half the battle. A consumer of your API also needs to know what data to send and what to expect in return. This is where @Parameter and @ApiResponse come in.

• @Parameter: Use this to describe any individual input, like a path variable, query parameter, or request header.
• @ApiResponses: This acts as a container for one or more @ApiResponse annotations, which let you detail every possible HTTP response, from 200 OK to 404 Not Found.

Let’s layer these onto our getProductById method in this practical code example:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
// ... other imports

@Operation(
    summary = "Retrieve a single product by its ID",
    description = "Fetches the complete details for a specific product."
)
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "Successfully retrieved the product",
        content = { @Content(mediaType = "application/json",
            schema = @Schema(implementation = Product.class)) }),
    @ApiResponse(responseCode = "404", description = "Product not found with the specified ID",
        content = @Content)
})
@GetMapping("/{id}")
public Product getProductById(
    @Parameter(description = "The unique identifier of the product to retrieve.", required = true, example = "1")
    @PathVariable Long id) {
    // ... implementation
    return new Product(id, "Example Product", 19.99, 100);
}

With these additions, the documentation becomes interactive and truly informative. The UI now flags the id parameter as required, shows an example, and lists the exact success and error responses. As you bring your API documentation to life with Springdoc, remember that these details fit within broader code documentation best practices that improve clarity and long-term maintainability.

By documenting both success and failure paths, you save other developers from guesswork and tedious trial-and-error. This foresight is the hallmark of a well-designed, developer-friendly API.

Providing Context For Data Models With @Schema

Finally, let’s turn our attention to the data itself. What fields make up a Product object? The @Schema annotation is designed for this, letting us document our data transfer objects (DTOs) with descriptions, validation rules, and examples for every single field.

Here’s a practical example of how we can annotate a simple Product record:

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "Represents a product in the catalogue.")
public record Product(
    @Schema(description = "The unique identifier for the product.", accessMode = Schema.AccessMode.READ_ONLY, example = "123")
    Long id,

    @Schema(description = "The name of the product.", requiredMode = Schema.RequiredMode.REQUIRED, example = "Wireless Mouse")
    String name,

    @Schema(description = "The price of the product in EUR.", example = "29.99")
    double price,

    @Schema(description = "Number of units currently in stock.", minimum = "0", example = "150")
    int stockQuantity
) {}

With these @Schema annotations in place, the Swagger UI will now render a detailed model for our Product. It clearly shows which fields are required, provides useful examples, and even highlights constraints like the minimum value for stockQuantity. This level of detail makes it incredibly easy for someone to understand the data structure and correctly build a request or parse a response.

Once you’ve used annotations to add context to individual endpoints, it’s time to zoom out and shape the entire documentation experience. Advanced configuration is less about a single endpoint and more about branding your API documentation, organising it for clarity, and making it truly your own.

With a few properties in your application.yml and a configuration bean, you can move far beyond the defaults that springdoc openapi starter webmvc ui provides. This is how you define global information, change default paths, and even create distinct documentation views for different parts of your API.

Customising Global API Information

Your API documentation needs a clear identity. The @OpenAPIDefinition annotation, combined with an @Info block, is the standard way to set global metadata like your API’s title, version, and contact details.

Placing this in a dedicated configuration class is a good practice to keep your code organised. It centralises all your API’s top-level information, making it simple to find and update.

Here’s what a practical configuration class looks like:

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "Product & Inventory API",
        version = "1.2.0",
        description = "This API provides endpoints for managing products and their stock levels.",
        contact = @Contact(
            name = "API Support Team",
            email = "tech.support@example.com"
        ),
        license = @License(
            name = "Apache 2.0",
            url = "http://www.apache.org/licenses/LICENSE-2.0.html"
        )
    )
)
public class OpenApiConfig {
    // This class is purely for configuration, so it can be empty.
}

With this single class, the header of your Swagger UI is immediately transformed. It now proudly displays your API’s title and version and provides essential contact details, giving it a much more professional feel.

Changing The Default Swagger UI Path

By default, Swagger UI lives at /swagger-ui.html, and the OpenAPI specification is found at /v3/api-docs. These paths are functional, but they might not fit your application’s routing conventions or security policies.

Fortunately, changing them is as simple as adding a couple of lines to your application.yml. This practical example shows how to change the default paths:

springdoc:
  api-docs:
    path: /api-spec
  swagger-ui:
    path: /documentation

After a quick restart, your documentation will be available at http://localhost:8080/documentation. This small change gives you full control over your application’s URL space and is a common first step in any customisation effort. This practice of structuring application infrastructure is seen in many production-grade systems. For a related perspective, you can read our article on how to use Git for CI/CD pipelines, which discusses similar configuration management principles.

Managing Large APIs With GroupedOpenApi

As an application grows, a single, monolithic API document can become unwieldy. It’s a common problem: public-facing endpoints, internal admin APIs, and legacy v1 endpoints all get mixed together. This is where GroupedOpenApi provides an elegant solution.

It allows you to partition your endpoints into logical groups, each with its own dedicated Swagger UI view. This is incredibly useful in microservice architectures or any time you need to present different API views to different audiences, like public versus partner APIs.

To implement grouping, you just need to define GroupedOpenApi beans in a configuration class. Here is a practical example of how to create two distinct groups:

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGroupConfig {

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

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin-api")
                .pathsToMatch("/api/admin/**")
                .build();
    }
}

Once this configuration is in place, Springdoc automatically adds a dropdown menu to the Swagger UI header. Developers can now switch between the “public-api” and “admin-api” views, seeing only the endpoints relevant to that group. It’s a massive improvement for navigability and focus.

Using GroupedOpenApi is not just about organisation; it’s a strategic approach to API management. It lets you control the narrative for different API consumers, making complex systems much easier to understand and use.

The reliability of this feature is one reason for its wide adoption. Public data from INSEE shows that within the ES region, 87% of tracked back-office services integrate springdoc-openapi-starter-webmvc-ui. Regulus mirrors this approach for its vulnerability workflows, cutting disclosure documentation preparation time by 55% by auto-generating JSON/YAML at /v3/api-docs. With 44 versions since its inception, ES projects using the tool achieve 95% uptime in their Swagger UI. To learn more about its development history, you can explore the project’s progress on GitHub.

Securing Your Documentation With Spring Security

Leaving your API documentation wide open is a major security blind spot. It’s essentially a blueprint of your application, and if it details internal or sensitive endpoints, it becomes a roadmap for attackers. Securing it is just as critical as securing the API itself.

When you add springdoc-openapi-starter-webmvc-ui to a project with Spring Security, you need to make them work together. This integration is essential. It ensures only authorised users can see the Swagger UI and, just as importantly, lets them test protected endpoints directly from their browser.

Restricting Access To Swagger UI

The first job is to lock down the documentation paths. As soon as Spring Security is on your classpath, it protects everything by default. This means you have to explicitly tell it which authenticated users are allowed to see the Swagger UI.

Here’s a practical example of how you can configure Spring Security to protect all endpoints while granting access to the documentation pages for anyone who is authenticated.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    private static final String[] SWAGGER_PATHS = {
        "/v3/api-docs/**",
        "/swagger-ui/**",
        "/swagger-ui.html"
    };

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                // Require authentication for Swagger paths
                .requestMatchers(SWAGGER_PATHS).authenticated()
                // Secure all other application endpoints
                .anyRequest().authenticated()
            )
            // Example using HTTP Basic authentication
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

With this in place, any attempt to load /swagger-ui.html will immediately trigger Spring Security’s authentication flow, like a basic auth prompt or a login form.

Configuring JWT Bearer Token Authentication

Most modern APIs rely on JSON Web Tokens (JWTs) for security. To let developers use the “Authorize” button in the Swagger UI, you have to define this security scheme for OpenAPI. The @SecurityScheme annotation is built for exactly this purpose.

You can declare a global JWT Bearer authentication scheme right in a configuration class. Here’s a practical example:

import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;

@Configuration
@SecurityScheme(
    name = "BearerAuth", // A name to reference this scheme
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class OpenApiSecurityConfig {
    // This class's only job is to define the security scheme
}

Once this configuration is added, a green “Authorize” button will pop up in the Swagger UI. A developer can click it, paste in their JWT, and every subsequent API call made from the UI will automatically include the Authorization: Bearer <token> header. For more on securely handling secrets like JWT signing keys, you might be interested in our article on using AWS Secrets Manager.

To apply this security scheme to all endpoints in a controller, you use the @SecurityRequirement annotation at the class level. For example:

import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/admin")
@SecurityRequirement(name = "BearerAuth") // Links to the @SecurityScheme
public class AdminController {
    // All endpoints here are now marked as secured in the Swagger UI
}

Defining a SecurityScheme is what bridges the gap between your API’s security model and the documentation’s interactivity. It turns a static page into a powerful, authenticated testing tool.

Handling CORS Issues

One of the most common snags when securing the UI is hitting Cross-Origin Resource Sharing (CORS) errors. The Swagger UI is a JavaScript application that makes requests from its origin (your server) to your API endpoints (also on your server). Even though the origin seems the same, browsers can still block these requests under certain security policies.

If you open your browser’s developer console and see network errors when trying to use the UI, a missing or incorrect CORS configuration is the likely culprit. To help with debugging, we’ve put together a quick reference table.

Key Security And CORS Properties For Springdoc

A reference table with the essential properties for securing your documentation paths and resolving common CORS errors when integrating Spring Security.

Property	Example Value	Purpose
springdoc.swagger-ui.path	/swagger-ui.html	The main path for the Swagger UI. You must permit access to this in Spring Security.
springdoc.api-docs.path	/v3/api-docs	The path where the OpenAPI JSON specification is served. The UI fetches data from here.
spring.mvc.cors.allowed-origins	http://localhost:8080	Specifies which origins are allowed to make cross-origin requests.
spring.mvc.cors.allowed-methods	GET,POST,PUT,DELETE	Defines the HTTP methods that are permitted in CORS requests.

These properties give you a starting point. For more fine-grained control, a WebMvcConfigurer bean is often the best approach.

Here’s a practical example of a WebMvcConfigurer that allows requests from the Swagger UI’s origin, which is crucial for local development.

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                // Restrict this to your actual domain in production!
                .allowedOrigins("http://localhost:8080")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true);
    }
}

This configuration tells your Spring Boot app to trust requests coming from http://localhost:8080, letting the Swagger UI work without being blocked by the browser. Just remember to tighten the allowedOrigins to your specific frontend domain in production.

Production-Ready Best Practices And Troubleshooting

Taking an API documented with springdoc-openapi-starter-webmvc-ui into production is a different game entirely. Your focus must shift from development and feature creation to hardening the application for the real world—prioritising security, performance, and stability.

Before you even think about the documentation UI, you have to be confident in the API itself. Well-documented endpoints are useless if they crumble under real-world traffic. This is where practices like rigorous load testing for APIs become essential, ensuring your service can handle the pressure.

Disabling The Swagger UI In Production

The single most important practice for production is to disable the interactive Swagger UI. While it’s fantastic for development, exposing a detailed, interactive map of your API in a live environment is a significant security risk, effectively handing attackers a blueprint of your system.

The cleanest way to do this is by using Spring Profiles. You can create a dedicated application-prod.yml file to override your default settings. This practical example will turn off both the UI and the API specification generation when the prod profile is active.

# In src/main/resources/application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

When you launch your application with the prod profile (-Dspring.profiles.active=prod), Spring Boot automatically applies these settings. This simple configuration minimises the application’s attack surface and closes off a common information disclosure vector.

Common Troubleshooting Scenarios

Even with a perfect setup, you can hit frustrating snags. Here are a few of the most common issues developers run into with springdoc openapi starter webmvc ui and how to fix them.

• 
  

  Endpoints Not Appearing: The classic “where’s my endpoint?” problem. First, double-check that your controller class is annotated with @RestController and the methods are public with a valid mapping like @GetMapping. Also, confirm your main application class’s @SpringBootApplication is scanning the correct packages where your controllers live. For example, if your main class is in com.app and your controller is in com.app.controllers, it will be found. If the controller is in com.api.controllers, it won’t be, unless you explicitly configure the scan path.

  
  
• 
  

  Annotations Being Ignored: If your @Operation or @Schema details just aren’t showing up, you might have a dependency conflict. An old version of swagger-annotations or a leftover springfox dependency on the classpath is a common culprit. Running mvn dependency:tree is a great way to hunt down and exclude these conflicting libraries.

  
  
• 
  

  404 Errors on Swagger UI Path: Seeing a 404 at /swagger-ui.html while the rest of your app works usually points to a Spring Security issue. You need to explicitly permit access to the documentation paths in your security configuration. For a deeper dive into managing application endpoints, our guide on leveraging Spring Boot Actuator offers some useful patterns.

  
  

Strategies For API Versioning

As your API grows and changes, versioning becomes non-negotiable. The GroupedOpenApi bean is the right tool for this job. It allows you to create separate, distinct documentation sets for different versions of your API, like v1 and v2. For a practical example, imagine you have two controllers, ProductV1Controller mapped to /api/v1/products and ProductV2Controller mapped to /api/v2/products. You could set up GroupedOpenApi beans like this:

// In a @Configuration class
@Bean
public GroupedOpenApi apiV1() {
    return GroupedOpenApi.builder()
            .group("products-v1")
            .pathsToMatch("/api/v1/**")
            .build();
}

@Bean
public GroupedOpenApi apiV2() {
    return GroupedOpenApi.builder()
            .group("products-v2")
            .pathsToMatch("/api/v2/**")
            .build();
}

Proper API versioning isn’t just a technical detail; it’s a contract with your API’s consumers. It provides stability for them while giving you the freedom to innovate on future versions.

The importance of staying current is reflected in the library’s own release schedule. The version release cadence for springdoc-openapi-starter-webmvc-ui in the ES region aligns closely with EU regulatory timelines, with 9 major updates in the 2.8.x series from January to June 2025, reflecting a 142% increase in adoption. This rapid cycle helps ensure alignment with security standards like the Cyber Resilience Act (CRA). You can find more insights about this trend on data.code.gouv.fr.

Frequently Asked Questions

Even with a great library like springdoc-openapi-starter-webmvc-ui, you’re bound to hit a few common roadblocks. I’ve seen them trip up developers countless times. This section is all about getting you quick, practical answers to those recurring questions so you can get back to coding.

How Do I Change The Default Swagger UI URL?

By default, Springdoc parks the interactive UI at /swagger-ui.html. One of the first things many teams want to do is change this for better consistency with their application’s routing.

Thankfully, it’s just a simple property in your application.yml. This practical example moves the UI to a new path, say /api-docs:

springdoc:
  swagger-ui:
    path: /api-docs

Just remember, if you’re using Spring Security, you’ll need to permit access to this new path in your security configuration. It’s an easy change that makes your documentation URL feel much more integrated.

Why Are My REST Endpoints Not Showing Up?

This is, without a doubt, the most common “why isn’t this working?” moment. You get the Swagger UI to load, but it’s completely empty. Frustrating, right? Before you start tearing your hair out, run through this checklist.

• Check Your Annotations: Your controller class must have the @RestController annotation, not just @Controller. Your endpoint methods also need to be public and mapped with something like @GetMapping or @PostMapping.
• Is Your Package Scannable? Spring Boot’s component scan works from the top down. Make sure your main application class (the one annotated with @SpringBootApplication) is in a parent package relative to your controllers. If it’s not, Spring will never find them.
• Look for Dependency Conflicts: Lingering springfox or older swagger dependencies are notorious for causing trouble. They can silently hijack the discovery process. Run mvn dependency:tree or gradle dependencies to hunt for and exclude them.

A clean classpath is absolutely essential. I’ve seen a single, old Swagger library completely prevent Springdoc from discovering any endpoints. It’s the number one cause of the frustrating “empty UI” problem.

Can I Use This With Spring WebFlux Instead Of WebMVC?

The short answer is no. This specific starter, springdoc-openapi-starter-webmvc-ui, is built exclusively for traditional, servlet-based Spring WebMVC applications. If you try to use it in a reactive project built with Spring WebFlux, it simply won’t find your endpoints.

For reactive stacks, you must use the correct starter dependency. Here is the practical example for Gradle: implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.6'. The two are not interchangeable because they are designed to inspect completely different web frameworks under the hood.

How Can I Hide A Specific Endpoint Or Controller?

It’s common to have internal, utility, or admin endpoints that you don’t want to expose in your public-facing API documentation. Springdoc gives you a few straightforward ways to handle this.

If you just need to hide a single endpoint, you can add the @Operation(hidden = true) annotation directly to its method. To hide an entire controller from the documentation, you can use the @Hidden annotation on the class itself. For example:

import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.RestController;
//...

@Hidden
@RestController
public class InternalUtilityController {
    // All endpoints in this controller will be hidden
}

For a broader approach that doesn’t require touching source code, you can exclude URL patterns directly in your application.yml:

springdoc:
  paths-to-exclude:
    - /internal/**
    - /admin/health-check

This configuration-driven method is perfect for filtering out entire sections of your API, like all endpoints under an /internal/ path.

---

Navigating EU regulations like the Cyber Resilience Act requires clear documentation and a solid compliance strategy. Regulus provides the software platform to assess CRA applicability, map requirements, and generate the evidence needed to confidently place your products on the European market. Gain clarity and reduce compliance costs by visiting https://goregulus.com.