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().setGroup("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().setGroup("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().setGroup("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().setGroup("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>

If you use Pageable in a GET HTTP method, you will have to declare the explicit mapping of Pageable fields as Query Params and add the @Parameter(hidden = true) Pageable pageable on your pageable parameter. You should also, declare the annotation @PageableAsQueryParam provided by springdoc on the method level, or declare your own if need to define your custom description, defaultvalue, …

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 the Doploy 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().setGroup("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);
}

back