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 can i disable ignored types:

If you don’t want to ignore the types Principal, Locale, HttpServletRequest, and others,:

    SpringDocUtils.getConfig().removeRequestWrapperToIgnore(HttpServletRequest.class)

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

How can i agreagte external endpoints (exposing OPENAPI 3 spec) inside one single application?

The properties springdoc.swagger-ui.urls.*, are suitable to configure external (/v3/api-docs url). For example if you want to agreagte all the endpoints of other services, inside one single application. Don’t forget that CORS needs to be enabled as well.

How can use custom json/yml file instead of generated one ?

If your file open-api.json, contains the OpenAPI documentation in OpenAPI 3 format. Then simply declare: The file name can be anything you want, from the moment your declaration is consistent yaml or json OpenAPI Spec.

	springdoc.swagger-ui.url=/open-api.json

Then the file open-api.json, should be located in: src/main/resources/static No additional configuration is needed.

How can i enable CSRF support?

If you are using standard headers.(for example using spring-security headers) If the CSRF Token is required, swagger-ui automatically sends the new XSRF-TOKEN during each HTTP REQUEST. That said - if your XSRF-TOKEN isn’t standards-based, you can use a requestInterceptor to manually capture and attach the latest xsrf token to requests programmatically via spring resource transformer:

Starting from release v1.4.4 of springdoc-openapi, a new property is added to enable CSRF support, while using standard header names:

    springdoc.swagger-ui.csrf.enabled=true

How can i disable the default swagger petstore URL?

You can use the following property:

springdoc.swagger-ui.disable-swagger-default-url=true

Is @PageableDefault supported, to enhance the OpenAPI 3 docuementation?

Yes, you can use it in conjunction with @ParameterObject annotation. Also, the spring-boot spring.data.web.* and spring.data.rest.default.* properties are supported since v1.4.5

How can i make spring security login-endpoint visible ?

You can use the following property:

springdoc.show-login-endpoint=true

How can i show schema definitions even the schema is not referenced?

You can use the following property:

springdoc.remove-broken-reference-definitions=false

How can i disable the swagger-ui from loading twince?

You can try the following property (if not using Oauth): This resolves a bug on swagger-ui where it loads some resources twice if using configurl as query parameter.

springdoc.swagger-ui.display-query-params-without-oauth2=true

Or if using Oauth2:

springdoc.swagger-ui.display-query-params	= true

How to override @Deprecated?

The whole idea of springdoc-openapi is to get your documentation the closest to the code, with minimal code changes. If the code contains @Deprecated, sprindoc-openapi will consider its schema as Deprecated as well. If you want to declare a field on swagger as non deprecated, even with the java code, the field contains @Depreacted, You can use the following property that is available since release v1.4.3:

springdoc.model-converters.deprecating-converter.enabled=false

How can i display a method that returns ModelAndView?

You can use the following property:

springdoc.model-and-view-allowed=true

How can i have pretty-printed output of the OpenApi specification?

You can use the following property:

springdoc.writer-with-default-pretty-printer=true

back