Springdoc OpenAPI

https://springdoc.org
Admin
Springdoc OpenAPI is a Java library that automates the generation of API documentation using Spring...
Tokens:72,509
Snippets:599
Trust Score:9.3
Update:5 days ago
Show doc for...
Tokens:
Raw
### Gradle dependency for springdoc-openapi-starter-webmvc-ui version 3.0.3

Source: https://springdoc.org/getting-started.html

Example using version 3.0.3 of the springdoc-openapi-starter-webmvc-ui dependency.

```groovy
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3'
```

--------------------------------

### Example management.server.port setting

Source: https://springdoc.org/modules.html

Example setting for the actuator management port. With this setting, the springdoc-openapi endpoints are available at http://serverName:9090/actuator, /actuator/swagger-ui, and /actuator/openapi.

```properties
management.server.port=9090
```

--------------------------------

### Add OpenAPI bean

Source: https://springdoc.org/migrating-from-springfox.html

Define an OpenAPI bean to customize API information and external documentation. This example shows a typical configuration.

```java
  @Bean
  public OpenAPI springShopOpenAPI() {
      return new OpenAPI()
              .info(new Info().title("SpringShop API")
              .description("Spring shop sample application")
              .version("v0.0.1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
              .externalDocs(new ExternalDocumentation()
              .description("SpringShop Wiki Documentation")
              .url("https://springshop.wiki.github.org/docs"));
  }
```

--------------------------------

### GET /api/mcp-admin/tools

Source: https://springdoc.org/mcp.html

Lists all available MCP tools. The response includes a 'group' field for each tool.

```APIDOC
## GET /api/mcp-admin/tools

### Description
Lists all available MCP tools. The response includes a 'group' field for each tool.

### Method
GET

### Endpoint
/api/mcp-admin/tools

### Response
#### Success Response (200)
- **tools** (array) - List of MCP tools, each with name, description, HTTP method, path, input schema, and group.

#### Response Example
{
  "tools": [
    {
      "name": "exampleTool",
      "description": "Example tool description",
      "method": "GET",
      "path": "/example",
      "inputSchema": {},
      "group": "exampleGroup"
    }
  ]
}
```

--------------------------------

### Integrate OpenAPI 3 with Spring (non-Boot): add spring-boot-autoconfigure dependency

Source: https://springdoc.org/faq.html

If you don't have spring-boot and spring-boot-autoconfigure dependencies, add them. Ensure compatibility between your spring.version and spring-boot.version. Example uses spring.version=5.1.12.RELEASE.

```xml
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-autoconfigure</artifactId>
			<version>3.3.3</version>
		</dependency>
```

--------------------------------

### Replace multiple Docket beans with GroupedOpenApi (Now)

Source: https://springdoc.org/migrating-from-springfox.html

After migration, use GroupedOpenApi beans to define groups. This example shows the equivalent configuration for public and admin APIs.

```java
  @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }
```

--------------------------------

### Change Swagger UI layout with springdoc.swagger-ui.layout

Source: https://springdoc.org/faq.html

Sets the layout of the Swagger UI. Example value 'BaseLayout'.

```properties
springdoc.swagger-ui.layout=BaseLayout

```

--------------------------------

### Return empty content in API response

Source: https://springdoc.org/faq.html

Use @Content or @Content(schema = @Schema(hidden = true)) in @ApiResponse to return an empty content. The example shows a GET endpoint with responses for success, not found, and authentication failure.

```java
@Operation(summary = "Get thing", responses = {
      @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = String.class))),
      @ApiResponse(responseCode = "404", description = "Not found", content = @Content),
      @ApiResponse(responseCode = "401", description = "Authentication Failure", content = @Content(schema = @Schema(hidden = true))) })
@RequestMapping(path = "/testme", method = RequestMethod.GET)
ResponseEntity<String> testme() {
   return ResponseEntity.ok("Hello");
}
```

--------------------------------

### Run Maven verify to test springdoc-openapi-maven-plugin

Source: https://springdoc.org/plugins.html

Use this command during the integration-tests phase to generate the OpenAPI description. The plugin works in conjunction with spring-boot-maven plugin.

```bash
mvn verify

```

--------------------------------

### @RouterOperation for a single functional endpoint

Source: https://springdoc.org/features.html

Use @RouterOperation on a @Bean method that returns a RouterFunction to document a single route. The @Operation annotation can be placed on the bean method level if the beanMethod property is declared. The operationId is mandatory. This example documents a GET /employees/{id} route with parameters and responses.

```java
@Bean
@RouterOperation(operation = @Operation(operationId = "findEmployeeById", summary = "Find purchase order by ID", tags = { "MyEmployee" },
      parameters = { @Parameter(in = ParameterIn.PATH, name = "id", description = "Employee Id") },
      responses = { @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Employee.class))),
            @ApiResponse(responseCode = "400", description = "Invalid Employee ID supplied"),
            @ApiResponse(responseCode = "404", description = "Employee not found") }))
RouterFunction<ServerResponse> getEmployeeByIdRoute() {
   return route(GET("/employees/{id}"),
         req -> ok().body(
               employeeRepository().findEmployeeById(req.pathVariable("id")), Employee.class));
}
```

--------------------------------

### @RouterOperations on a Function bean to customize multiple REST APIs

Source: https://springdoc.org/modules.html

Use @RouterOperations to describe multiple REST APIs exposed by spring-cloud-function-web. The method property is mandatory when using @RouterOperations. This example defines a Function<Flux<String>, Flux<String>> bean with GET and POST operations, each with its own operationId and tags.

```java
@Bean
@RouterOperations({
        @RouterOperation(method = RequestMethod.GET, operation = @Operation(description = "Say hello GET", operationId = "lowercaseGET", tags = "persons")),
        @RouterOperation(method = RequestMethod.POST, operation = @Operation(description = "Say hello POST", operationId = "lowercasePOST", tags = "positions"))
})
public Function<Flux<String>, Flux<String>> lowercase() {
    return flux -> flux.map(value -> value.toLowerCase());
}
```

--------------------------------

### Set context-path with server.servlet.context-path

Source: https://springdoc.org/faq.html

When a different context-path is set, the swagger-ui will be available at http://server:port/foo/swagger-ui.html.

```properties
server.servlet.context-path= /foo
```

--------------------------------

### Functional DSL for webflux/WebMvc.fn routes

Source: https://springdoc.org/features.html

Sample DSL to generate OpenAPI description for webflux/WebMvc.fn REST endpoints. Uses route().GET() with operationId, parameters, and responses.

```java
@Bean
RouterFunction<?> routes() {
    return route().GET("/foo", HANDLER_FUNCTION, ops -> ops
            .operationId("hello")
            .parameter(parameterBuilder().name("key1").description("My key1 description"))
            .parameter(parameterBuilder().name("key2").description("My key2 description"))
            .response(responseBuilder().responseCode("200").description("This is normal response description"))
            .response(responseBuilder().responseCode("404").description("This is another response description"))
    ).build();
}
```

--------------------------------

### Expose MVC api-docs endpoints with springdoc-openapi-starter-webmvc-api

Source: https://springdoc.org/faq.html

Use only the springdoc-openapi-core dependency (here the starter-webmvc-api artifact) to expose the api-docs endpoints without the swagger-ui.

```xml
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
  <version>latest.version</version>
</dependency>
```

--------------------------------

### Set paths to match

Source: https://springdoc.org/

Sets springdoc.pathsToMatch to a list of paths to include in the documentation.

```properties
springdoc.pathsToMatch=/v1, /api/balance/**
```

--------------------------------

### Add springdoc-openapi-starter-webmvc-api dependency

Source: https://springdoc.org/modules.html

Maven dependency for generating the OpenAPI description without Swagger-UI in a Spring WebMvc project. No additional configuration is needed. Documentation is available at /v3/api-docs (JSON) and /v3/api-docs.yaml.

```xml
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>3.1.1</version>
   </dependency>
```

--------------------------------

### Enable pretty-printed OpenAPI output with springdoc.writer-with-default-pretty-printer

Source: https://springdoc.org/faq.html

Set this property to true to get pretty-printed output of the OpenAPI specification.

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

--------------------------------

### Define a GroupedOpenApi bean for paths matching /pet/**

Source: https://springdoc.org/faq.html

Creates a GroupedOpenApi bean with group name 'pets' that matches paths /pet/**. The OpenAPI description URL will be /v3/api-docs/pets.

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

```

--------------------------------

### Control default expansion setting with springdoc.swagger-ui.doc-expansion

Source: https://springdoc.org/faq.html

Sets the default expansion setting for operations and tags in Swagger UI. Example value 'none'.

```properties
springdoc.swagger-ui.doc-expansion= none

```

--------------------------------

### Configure single Docket via application.properties

Source: https://springdoc.org/migrating-from-springfox.html

If you have only one Docket, remove it and add these properties to application.properties to configure package scanning and path matching.

```properties
springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
```

--------------------------------

### Add springdoc-openapi-starter-webflux-api dependency

Source: https://springdoc.org/modules.html

Maven dependency for generating the OpenAPI description without Swagger-UI in a Spring WebFlux project. No additional configuration is needed. Documentation is available at /v3/api-docs.yaml.

```xml
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webflux-api</artifactId>
      <version>3.1.1</version>
   </dependency>
```

--------------------------------

### Add springdoc-openapi-starter-webmvc-ui dependency

Source: https://springdoc.org/modules.html

Maven dependency for Swagger-UI support in a Spring WebMvc project (using spring-boot-starter-web). No additional configuration is needed.

```xml
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>3.1.1</version>
   </dependency>
```

--------------------------------

### Hide response schema at @ApiResponses level

Source: https://springdoc.org/faq.html

Alternatively, hide the response schema directly at the @ApiResponses level. The example also shows a 404 response without a schema.

```java
@ApiResponses(value = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))) })
OR
@ApiResponse(responseCode = "404", description = "Not found", content = @Content)
```

--------------------------------

### Exclude endpoints via context.setExclude(true)

Source: https://springdoc.org/mcp.html

Defines a McpToolCustomizer that excludes DELETE methods and paths starting with /internal by setting context.setExclude(true). This is preferred over returning null.

```java
@Bean
McpToolCustomizer excludeDeleteAndInternal() {
    return (context, path, method, operation) -> {
        if (method == PathItem.HttpMethod.DELETE || path.startsWith("/internal")) {
            context.setExclude(true);
        }
        return context;
    };
}
```

--------------------------------

### Define a GroupedOpenApi bean for paths matching /store/**

Source: https://springdoc.org/faq.html

Creates a GroupedOpenApi bean with group name 'stores' that matches paths /store/**. The OpenAPI description URL will be /v3/api-docs/stores.

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

```

--------------------------------

### Add springdoc-openapi-starter-webmvc-scalar dependency

Source: https://springdoc.org/modules.html

Maven dependency for Scalar support in a Spring WebMvc project (using spring-boot-starter-web). The Scalar UI is available at /scalar and the OpenAPI description at /v3/api-docs.

```xml
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-scalar</artifactId>
      <version>3.1.1</version>
   </dependency>
```

--------------------------------

### Custom MonetaryAmount schema with replaceWithSchema

Source: https://springdoc.org/faq.html

Alternative solution without using springdoc-openapi's MonetaryAmount support. It defines a custom schema with amount and currency properties, including examples.

```java
SpringDocUtils.getConfig().replaceWithSchema(MonetaryAmount.class, new ObjectSchema()
            .addProperties("amount", new NumberSchema()).example(99.96)
            .addProperties("currency", new StringSchema().example("USD")));
```
Tokens:
Raw