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

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

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

@Bean
public GroupedOpenApi userOpenApi() {
	String packagesToscan[] = {"test.org.springdoc.api.app68.api.user"};
	return GroupedOpenApi.builder().group("users").packagesToScan(packagesToscan)
			.build();
}

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

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

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

@Bean
public GroupedOpenApi groupOpenApi() {
	String paths[] = {"/v1/**"};
	String packagesToscan[] = {"test.org.springdoc.api.app68.api.user", "test.org.springdoc.api.app68.api.store"};
	return GroupedOpenApi.builder().group("groups").pathsToMatch(paths).packagesToScan(packagesToscan)
			.build();
}

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 ?

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-security</artifactId>
	<version>last.version</version>
</dependency>

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:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>latest.version</version>
</dependency>

How can I generate enums in the generated description?

@GetMapping("/example")
public Object example(@Parameter(name ="json", schema = @Schema(description = "var 1",type = "string", allowableValues = {"1", "2"}))
String json) {
   return null;
}
@Override
@JsonValue
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 ?

@Bean
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?

@Bean
 public OpenAPI customOpenAPI() {
   return new OpenAPI()
          .components(new Components()
          .addSecuritySchemes("bearer-key", 
          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?

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-core</artifactId>
  <version>latest.version</version>
</dependency> 

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?

@Bean
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("http://springdoc.org")));
}
GroupedOpenApi.builder().group("users").pathsToMatch(paths).packagesToScan(packagedToMatch).addOpenApiCustomiser(customerGlobalHeaderOpenApiCustomiser())
                .build()

@Bean
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 {
	SpringDocUtils.getConfig().addRestControllers(HelloController.class);
}

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:

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>last.version</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot</artifactId>
    <version>2.1.11.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure</artifactId>
    <version>2.1.11.RELEASE</version>
</dependency>
@EnableWebMvc
public class AppInitializer implements WebApplicationInitializer {

	@Override
	public void onStartup(ServletContext servletContext) throws ServletException {
		WebApplicationContext context = getContext();
		servletContext.addListener(new ContextLoaderListener(context));
		ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
				new DispatcherServlet(context));
		dispatcher.setLoadOnStartup(1);
		dispatcher.addMapping("/*");
	}

	private AnnotationConfigWebApplicationContext getContext() {
		AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
		context.scan("rest");
		context.register(this.getClass(), org.springdoc.ui.SwaggerConfig.class,
				org.springdoc.core.SwaggerUiConfigProperties.class, org.springdoc.core.SwaggerUiOAuthProperties.class,
				org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
				org.springdoc.webmvc.core.MultipleOpenApiSupportConfiguration.class,
				org.springdoc.core.SpringDocConfiguration.class, org.springdoc.core.SpringDocConfigProperties.class,
				org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class);
		
		return context;
	}
}

How can I use the last springdoc-openapi SNAPSHOT ?

     <repositories>
       <repository>
         <id>snapshots-repo</id>
         <url>https://oss.sonatype.org/content/repositories/snapshots</url>
         <releases><enabled>false</enabled></releases>
         <snapshots><enabled>true</enabled></snapshots>
       </repository>
     </repositories>

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")));

back