Skip to the content.

Welcome to FAQ

How can I define multiple OpenAPI definitions in one Spring Boot project?

You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique groupName. The OpenAPI description of this group, will be available by default on:

To enable the support of multiple OpenAPI definitions, a bean of type GroupedOpenApi needs to be defined.

For the following Group definition(based on package path), the OpenAPI description URL will be : /v3/api-docs/stores

public GroupedOpenApi storeOpenApi() {
	String paths[] = {"/store/**"};
	return GroupedOpenApi.builder().group("stores").pathsToMatch(paths)

For the following Group definition (based on package name), the OpenAPI description URL will be: /v3/api-docs/users

public GroupedOpenApi userOpenApi() {
	String packagesToscan[] = {""};
	return GroupedOpenApi.builder().group("users").packagesToScan(packagesToscan)

For the following Group definition(based on path), the OpenAPI description URL will be: /v3/api-docs/pets

public GroupedOpenApi petOpenApi() {
	String paths[] = {"/pet/**"};
	return GroupedOpenApi.builder().group("pets").pathsToMatch(paths)

For the following Group definition (based on package name and path), the OpenAPI description URL will be: /v3/api-docs/groups

public GroupedOpenApi groupOpenApi() {
	String paths[] = {"/v1/**"};
	String packagesToscan[] = {"", ""};
	return GroupedOpenApi.builder().group("groups").pathsToMatch(paths).packagesToScan(packagesToscan)

For more details about the usage, you can have a look at the following sample Test:

How can I configure Swagger UI?

How can I filter the resources documented in the output specification by the provided group?

How can I disable/enable Swagger UI generation based on env variable?

How can I change the layout of the swagger-ui?

How can I sort endpoints alphabetically?

How can I disable the try it out button?

How can I add Reusable Enums ?

How can I explicitly set which paths to filter?

How can I explicitly set which packages to scan?

How can I ignore some field of model ?

How can I ignore @AuthenticationPrincipal parameter from spring-security ?


Is there a Gradle plugin available?

How can I hide a parameter from the documentation ?

Is @Parameters annotation supported ?

Does springdoc-openapi support Jersey?

Can springdoc-openapi generate API only for @RestController?

Are the following validation annotations supported : @NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero?

How can I map Pageable (spring-date-commons) object to correct URL-Parameter in Swagger UI?

The projects that uses spring-data should add this dependency together with the springdoc-openapi-ui dependency:


How can I generate enums in the generated description?

public Object example(@Parameter(name ="json", schema = @Schema(description = "var 1",type = "string", allowableValues = {"1", "2"}))
String json) {
   return null;
public String toString() {
	return String.valueOf(action);

Does it really support Spring Boot 2.2.x.RELEASE & HATEOAS 1.0?

How can I deploy springdoc-openapi-ui behind a reverse proxy?

Is @JsonView annotations in Spring MVC APIs supported?

Adding springdoc-openapi-ui dependency breaks my public/index.html welcome page

How can I test the Swagger UI?

How can I customise the OpenAPI object ?

public OpenAPICustomiser consumerTypeHeaderOpenAPICustomiser() {
return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
    .forEach(operation -> operation.addParametersItem(new HeaderParameter().$ref("#/components/parameters/myConsumerTypeHeader")));

How to include spring-boot-actuator endpoints to Swagger UI?

How can I return an empty content as response?

How are endpoints with multiple consuming media types supported?

How can I get yaml and json (OpenAPI) in compile time?

What are the ignored types in the documentation?

How do I add authorization header in requests?

 public OpenAPI customOpenAPI() {
   return new OpenAPI()
          .components(new Components()
          new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));

Differentiation to Springfox project

How do I migrate to OpenAPI 3 with springdoc-openapi

How can I set a global header?

How can I define SecurityScheme ?

How can I hide an operation or a controller from documentation ?

How to configure global security schemes?

How is server URL generated ?

How can I expose the api-docs endpoints without using the swagger-ui?


How can I disable springdoc-openapi endpoints ?

How can I hide Schema of the the response ?

What is the URL of the swagger-ui, when I set a different context-path?

Can I customize OpenAPI object programmatically?

public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
	return new OpenAPI()
    .components(new Components().addSecuritySchemes("basicScheme",
            new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
    .info(new Info().title("SpringShop API").version(appVersion)
            .license(new License().name("Apache 2.0").url("")));

public OpenApiCustomiser customerGlobalHeaderOpenApiCustomiser() {
	return openApi -> openApi.path("/foo",
	new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
	.addApiResponse("default",new ApiResponse().description("")
	.content(new Content().addMediaType("fatz", new MediaType()))))));

Where can I find the source code of the demo applications?

Does this library supports annotations from interfaces?

What is the list of the excluded parameter types?

Is file upload supported ?

Can I use @Parameter inside @Operation annotation?

Why my parameter is marked as required?

How are overloaded methods with the same endpoints, but with different parameters

What is a proper way to set up Swagger UI to use provided spec.yml?

Is there a way to send authorization header through the @Parameter tag?

My Rest Controller using @Controller annotation is ignored?

static {

How can I define groups using application.yml?

How can I extract fields from parameter object ?

Where can I find a tutorial of using springdoc-openapi ?

How to Integrate Open API 3 with Spring project (not Spring Boot)?

When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.

For example, lets assume you want load the swagger-ui in spring-mvc application:

public class AppInitializer implements WebApplicationInitializer {

	public void onStartup(ServletContext servletContext) throws ServletException {
		WebApplicationContext context = getContext();
		servletContext.addListener(new ContextLoaderListener(context));
		ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
				new DispatcherServlet(context));

	private AnnotationConfigWebApplicationContext getContext() {
		AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
		context.register(this.getClass(), org.springdoc.ui.SwaggerConfig.class,
				org.springdoc.core.SwaggerUiConfigProperties.class, org.springdoc.core.SwaggerUiOAuthProperties.class,
				org.springdoc.core.SpringDocConfiguration.class, org.springdoc.core.SpringDocConfigProperties.class,
		return context;

How can I use the last springdoc-openapi SNAPSHOT ?


How can I use enable springdoc-openapi MonetaryAmount support ?

SpringDocUtils.getConfig().replaceWithClass(MonetaryAmount.class, org.springdoc.core.converters.MonetaryAmount.class);
SpringDocUtils.getConfig().replaceWithSchema(MonetaryAmount.class, new ObjectSchema()
				.addProperties("amount", new NumberSchema()).example(99.96)
				.addProperties("currency", new StringSchema().example("USD")));