Springdoc-openapi Modules

General overview

Architecture

Spring WebMvc support

  • Documentation will be available at the following url for json format: http://server:port/context-path/v3/api-docs

    • server: The server name or IP

    • port: The server port

    • context-path: The context path of the application

  • Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml

  • Add the library to the list of your project dependencies. (No additional configuration is needed)

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-webmvc-core</artifactId>
      <version>1.8.0</version>
   </dependency>
This dependency is relevant if you want to generate the OpenAPI description without using the swagger-ui.
For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file: 
# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs

Spring WebFlux support

  • Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yaml

  • Add the library to the list of your project dependencies (No additional configuration is needed)

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-webflux-ui</artifactId>
      <version>1.8.0</version>
   </dependency>

Spring Hateoas support

The support for Spring Hateoas is available using the dependency springdoc-openapi-hateoas. The projects that use Spring Hateoas should combine this dependency with the springdoc-openapi-ui dependency. This dependency enables the support of Spring Hateoas format.

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-hateoas</artifactId>
      <version>1.8.0</version>
   </dependency>

Spring Data Rest support

The projects that use spring-data-rest can add the following dependency in combination with the springdoc-openapi-ui dependency. This dependency enables the support of spring-boot-starter-data-rest types like: @RepositoryRestResource and QuerydslPredicate annotations.

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

Spring Security support

For a project that uses spring-security, you should add the following dependency, in combination with the springdoc-openapi-ui dependency: This dependency helps ignoring @AuthenticationPrincipal in case its used on REST Controllers.

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

Actuator support

  • In order to display spring-boot-actuator endpoints, simply add the following property:

springdoc.show-actuator=true

Starting from the release 1.5.1, it will be possible to expose the swagger-ui and the openapi endpoints on actuator port.

The actuator management port has to be different from the application port.

To expose the swagger-ui, on the management port, you should set

springdoc.use-management-port=true
# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
management.endpoints.web.exposure.include=openapi, swagger-ui

Once enabled, you should also be able to see the springdoc-openapi endpoints under: (host and port depends on your settings) - http://serverName:managementPort/actuator

For example, if you have the following settings:

Two endpoints will be available:

  1. REST API that holdes the OpenAPI definition:

    • http://serverName:managementPort/actuator/openapi

  2. An Endpoint, that routes to the swagger-ui:

    • http://serverName:managementPort/actuator/swagger-ui

management.server.port=9090

For the example, you should also be able to see the springdoc-openapi endpoints:

  • http://serverName:9090/actuator

  • http://serverName:9090/actuator/swagger-ui

  • http://serverName:9090/actuator/openapi

All the path springdoc-openapi properties are not applicable when springdoc.use-management-port=true.

If you want to reach the application endpoints, from the swagger-ui deployed beneath the actuator base path, using a different port from your application, CORS for your endpoints on your application level should be enabled.

Additionally, it is also possible to combine this property, with the existing property to display the actuator endpoints in the swagger-ui.

springdoc.show-actuator=true

Once enabled: - A dedicated group for the actuator endpoints will be by default added. - If no group is defined for the application, a default one will be added.

The swagger-ui will be then accessible through the actuator port:

  • http://serverName:managementPort/actuator/swagger-ui

If the management port is different from the application port and springdoc.use-management-port is not defined but springdoc.show-actuator is set to true:

  • The swagger-ui will be then accessible through the application port. For example: http://serverName:applicationPort/swagger-ui.html

  • A dedicated group for the actuator endpoints will be by default added.

  • If no group is defined for the application, a default one will be added.

If you want to reach the actuator endpoints for this case (different port from your application), CORS for your actuator endpoints should be enabled.

Note: The naming of these new endpoints beneath the actuator base path cannot be customized for now.

Spring Cloud Function Web support

spring-cloud-function-web exposes Java Function as REST endpoint automatically. * Since version v1.6.3, the support of functional endpoints has been added.

  • These starters will display the OpenAPI description of the spring-cloud-function-web endpoints.

    • If you are using spring-web, simply add the springdoc-openapi-ui dependency.

    • If you are using spring-webflux, simply add the springdoc-openapi-webflux-ui dependency.

The customisation of the output can be achieved programmatically through OpenApiCustomizer or with the annotations: @RouterOperations and @RouterOperation. For annotation usage, you have: * @RouterOperation: It can be used alone, if the customisation is related to a single REST API. When using @RouterOperation, it’s not mandatory to fill the path

  • @RouterOperation, contains the @Operation annotation. The @Operation annotation can also be placed on the bean method level if the property beanMethod is declared.

Don’t forget to set operationId which is mandatory. 
@Bean
@RouterOperation(operation = @Operation(description = "Say hello", operationId = "hello", tags = "persons",
        responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PersonDTO.class)))))
public Supplier<PersonDTO> helloSupplier() {
    return () -> new PersonDTO();
}

  • @RouterOperations: This annotation should be used to describe the multiple REST APIs exposed by spring-cloud-function-web. When using RouterOperations, it’s mandatory to fill the method property.

  • A @RouterOperations, contains many @RouterOperation.

@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());
}

Some code samples are available on GITHUB of demos:

Kotlin support

For a project that uses Kotlin, you should add the following dependency. This dependency improves the support of Kotlin types:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-kotlin</artifactId>
      <version>1.8.0</version>
   </dependency>

  • If you are using spring-web, you should combine the springdoc-openapi-kotlin module with springdoc-openapi-ui.

  • If you are using spring-webflux, you should combine the springdoc-openapi-kotlin module with springdoc-openapi-webflux-ui.

Groovy support

For a project that uses Groovy, you should add the following dependency, in combination with the springdoc-openapi-ui dependency: This dependency improves the support of Kotlin types:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-groovy</artifactId>
      <version>1.8.0</version>
   </dependency>

Javadoc support

For a project that wants to enable javadoc support, you should add the following dependency, in combination with the springdoc-openapi-ui dependency:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-javadoc</artifactId>
      <version>1.8.0</version>
   </dependency>

This dependency improves the support of javadoc tags and comments:

  • The javadoc comment of a method: is resolved as the @Operation description

  • @return : is resolved as the @Operation response description

  • The javadoc comment of an attribute: is resolved as '@Schema' description for this field.

This dependency is based on the library therapi-runtime-javadoc

Make sure, you enable the annotation processor of therapi-runtime-javadoc in order to enable javadoc support for springdoc-openapi. 
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<annotationProcessorPaths>
						<path>
							<groupId>com.github.therapi</groupId>
							<artifactId>therapi-runtime-javadoc-scribe</artifactId>
							<version>0.15.0</version>
						</path>
					</annotationProcessorPaths>
				</configuration>
			</plugin>
		</plugins>
	</build>
If both a swagger-annotation description and a javadoc comment are present. The value of the swagger-annotation description will be used.