<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.15">
<title>Springdoc-openapi Modules</title>
<link rel="stylesheet" href="css/site.css">
<script src="js/setup.js"></script><script defer src="js/site.js"></script>
</head>
<body class="article"><div id="banner-container" class="container" role="banner">
<div id="banner" class="contained" role="banner">
<div id="switch-theme">
<input type="checkbox" id="switch-theme-checkbox" />
<label for="switch-theme-checkbox">Dark Theme</label>
</div>
</div>
</div>
<div id="tocbar-container" class="container" role="navigation">
<div id="tocbar" class="contained" role="navigation">
<button id="toggle-toc"></button>
</div>
</div>
<div id="main-container" class="container">
<div id="main" class="contained">
<div id="doc" class="doc">
<div id="header">
</div>
<div id="content">
<div class="sect1">
<h2 id="modules"><a class="anchor" href="#modules"></a>Springdoc-openapi Modules</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_general_overview"><a class="anchor" href="#_general_overview"></a>General overview</h3>
<div class="imageblock">
<div class="content">
<img src="img/common.png" alt="Architecture">
</div>
</div>
</div>
<div class="sect2">
<h3 id="_spring_webmvc_support"><a class="anchor" href="#_spring_webmvc_support"></a>Spring WebMvc support</h3>
<div class="ulist">
<ul>
<li>
<p>Documentation will be available at the following url for json format: <code>http://server:port/context-path/v3/api-docs</code></p>
<div class="ulist">
<ul>
<li>
<p>server: The server name or IP</p>
</li>
<li>
<p>port: The server port</p>
</li>
<li>
<p>context-path: The context path of the application</p>
</li>
</ul>
</div>
</li>
<li>
<p>Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml</p>
</li>
<li>
<p>Add the library to the list of your project dependencies. (No additional configuration is needed)</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> <dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.8.6</version>
</dependency></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This dependency is relevant if you want to generate the OpenAPI description without using the swagger-ui.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties"># /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_spring_webflux_support"><a class="anchor" href="#_spring_webflux_support"></a>Spring WebFlux support</h3>
<div class="ulist">
<ul>
<li>
<p>Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml</p>
</li>
<li>
<p>Add the library to the list of your project dependencies (No additional configuration is needed)</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> <dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webflux-api</artifactId>
<version>2.8.6</version>
</dependency></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_spring_hateoas_support"><a class="anchor" href="#_spring_hateoas_support"></a>Spring Hateoas support</h3>
<div class="paragraph">
<p>The support for Spring Hateoas is available using the dependency springdoc-openapi-hateoas.</p>
</div>
<div class="paragraph">
<p>The projects that use <code>spring-boot-starter-hateoas</code> should use:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>springdoc-openapi-starter-webmvc-api</code> if they need only the access to the OpenAPI endpoints</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webmvc-ui</code>, if they need also the access to the swagger-ui</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_spring_data_rest_support"><a class="anchor" href="#_spring_data_rest_support"></a>Spring Data Rest support</h3>
<div class="paragraph">
<p><code>springdoc-openapi</code> project supports <code>spring-boot-starter-data-rest</code> types like: <code>@RepositoryRestResource</code> and <code>QuerydslPredicate</code> annotations.</p>
</div>
<div class="paragraph">
<p>The projects that use <code>spring-boot-starter-data-rest</code> should use:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>springdoc-openapi-starter-webmvc-api</code> if they need only the access to the OpenAPI endpoints</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webmvc-ui</code>, if they need also the access to the swagger-ui</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_spring_security_support"><a class="anchor" href="#_spring_security_support"></a>Spring Security support</h3>
<div class="paragraph">
<p><code>springdoc-openapi</code> helps ignoring @AuthenticationPrincipal type in case it is used on REST Controllers.</p>
</div>
<div class="paragraph">
<p><code>springdoc-openapi</code> supports also exposing Oauth2 endpoints of <code>spring-security-oauth2-authorization-server</code>.</p>
</div>
<div class="paragraph">
<p>The projects that use <code>spring-boot-starter-security</code> or <code>spring-security-oauth2-authorization-server</code> should use:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>springdoc-openapi-starter-webmvc-api</code> if they depend on <code>spring-boot-starter-web</code> and they only need the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webmvc-ui</code>, if they depend on <code>spring-boot-starter-web</code> and they also need the access to the swagger-ui.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-api</code> if they depend on <code>spring-boot-starter-webflux</code> and they only the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-ui</code>, if they depend on <code>spring-boot-starter-webflux</code> and they also need the access to the swagger-ui.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_actuator_support"><a class="anchor" href="#_actuator_support"></a>Actuator support</h3>
<div class="ulist">
<ul>
<li>
<p>In order to display <code>spring-boot-actuator</code> endpoints, simply add the following property:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">springdoc.show-actuator=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Starting from the release <code>1.5.1</code>, it will be possible to expose the <strong>swagger-ui</strong> and the <strong>openapi</strong> endpoints on <strong>actuator port</strong>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The actuator management port has to be different from the application port.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To expose the swagger-ui, on the management port, you should set</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">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</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once enabled, you should also be able to see the springdoc-openapi endpoints under: (host and port depends on your settings)
- <code>http://serverName:managementPort/actuator</code></p>
</div>
<div class="paragraph">
<p>For example, if you have the following settings:</p>
</div>
<div class="paragraph">
<p>Two endpoints will be available:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>REST API that holdes the OpenAPI definition:</p>
<div class="ulist">
<ul>
<li>
<p><code>http://serverName:managementPort/actuator/openapi</code></p>
</li>
</ul>
</div>
</li>
<li>
<p>An Endpoint, that routes to the swagger-ui:</p>
<div class="ulist">
<ul>
<li>
<p><code>http://serverName:managementPort/actuator/swagger-ui</code></p>
</li>
</ul>
</div>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">management.server.port=9090</code></pre>
</div>
</div>
<div class="paragraph">
<p>For the example, you should also be able to see the springdoc-openapi endpoints:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>http://serverName:9090/actuator</code></p>
</li>
<li>
<p><code>http://serverName:9090/actuator/swagger-ui</code></p>
</li>
<li>
<p><code>http://serverName:9090/actuator/openapi</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>All the path <code>springdoc-openapi</code> properties are not applicable when <code>springdoc.use-management-port=true</code>.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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, <code>CORS for your endpoints</code> on your application level should be enabled.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Additionally, it is also possible to combine this property, with the existing property to display the actuator endpoints in the swagger-ui.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">springdoc.show-actuator=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>The swagger-ui will be then accessible through the actuator port:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>http://serverName:managementPort/actuator/swagger-ui</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If the management port is different from the application port and <code>springdoc.use-management-port</code> is not defined but <code>springdoc.show-actuator</code> is set to true:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The swagger-ui will be then accessible through the application port. For example: <code>http://serverName:applicationPort/swagger-ui.html</code></p>
</li>
<li>
<p>A dedicated group for the actuator endpoints will be by default added.</p>
</li>
<li>
<p>If no group is defined for the application, a default one will be added.</p>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If you want to reach the actuator endpoints for this case (different port from your application), <code>CORS</code> for your actuator endpoints should be enabled.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Note: The naming of these new endpoints beneath the actuator base path cannot be customized for now.</p>
</div>
</div>
<div class="sect2">
<h3 id="_spring_cloud_function_web_support"><a class="anchor" href="#_spring_cloud_function_web_support"></a>Spring Cloud Function Web support</h3>
<div class="paragraph">
<p><code>spring-cloud-function-web</code> exposes Java Function as REST endpoint automatically.
* Since version <code>v1.6.3</code>, the support of functional endpoints has been added.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>These starters will display the OpenAPI description of the <code>spring-cloud-function-web</code> endpoints.</p>
<div class="ulist">
<ul>
<li>
<p>If you are using <code>spring-web</code>, simply add the <code>springdoc-openapi-starter-webmvc-ui</code> dependency.</p>
</li>
<li>
<p>If you are using <code>spring-webflux</code>, simply add the <code>springdoc-openapi-starter-webflux-ui</code> dependency.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>The customisation of the output can be achieved programmatically through <code>OpenApiCustomizer</code> or with the annotations: <code>@RouterOperations</code> and <code>@RouterOperation</code>.
For annotation usage, you have:
* <code>@RouterOperation</code>: It can be used alone, if the customisation is related to a single REST API.
When using <code>@RouterOperation</code>, it’s not mandatory to fill the path</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>@RouterOperation</code>, contains the <code>@Operation</code> annotation.
The <code>@Operation</code> annotation can also be placed on the bean method level if the property beanMethod is declared.</p>
</li>
</ul>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Don’t forget to set <strong>operationId</strong> which is <strong>mandatory</strong>.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">@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();
}
</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><code>@RouterOperations</code>: This annotation should be used to describe the multiple REST APIs exposed by <code>spring-cloud-function-web</code>.
When using <code>RouterOperations</code>, it’s mandatory to fill the method property.</p>
</li>
<li>
<p>A <code>@RouterOperations</code>, contains many <code>@RouterOperation</code>.</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="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());
}
</code></pre>
</div>
</div>
<div class="paragraph">
<p>Some code samples are available on GITHUB of demos:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/springdoc/springdoc-openapi-demos/tree/master/demo-spring-cloud-function" target="_blank" rel="noopener">Sample applications with Spring Cloud Function Web</a></p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_kotlin_support"><a class="anchor" href="#_kotlin_support"></a>Kotlin support</h3>
<div class="paragraph">
<p><code>springdoc-openapi</code> supports Kotlin types.</p>
</div>
<div class="paragraph">
<p>The projects that use <code>Kotlin</code> should use:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>springdoc-openapi-starter-webmvc-api</code> if they depend on <code>spring-boot-starter-web</code> and they only need the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webmvc-ui</code>, if they depend on <code>spring-boot-starter-web</code> and they also need the access to the swagger-ui.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-api</code> if they depend on <code>spring-boot-starter-webflux</code> and they only the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-ui</code>, if they depend on <code>spring-boot-starter-webflux</code> and they also need the access to the swagger-ui.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
In addition, your project should add <code>jackson-module-kotlin</code> as well to have the full support of <code>Kotlin</code> types:
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> <dependency>
<groupId>com.fasterxml.jackson.module</groupId>
<artifactId>jackson-module-kotlin</artifactId>
</dependency></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_groovy_support"><a class="anchor" href="#_groovy_support"></a>Groovy support</h3>
<div class="paragraph">
<p>The projects that use <code>Groovy</code> should use:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>springdoc-openapi-starter-webmvc-api</code> if they depend on <code>spring-boot-starter-web</code> and they only need the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webmvc-ui</code>, if they depend on <code>spring-boot-starter-web</code> and they also need the access to the swagger-ui.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-api</code> if they depend on <code>spring-boot-starter-webflux</code> and they only the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-ui</code>, if they depend on <code>spring-boot-starter-webflux</code> and they also need the access to the swagger-ui.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_javadoc_support"><a class="anchor" href="#_javadoc_support"></a>Javadoc support</h3>
<div class="paragraph">
<p><code>springdoc-openapi</code> can introspect <code>Javadoc</code> annotations and comments:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The javadoc comment of a method: is resolved as the <code>@Operation</code> description</p>
</li>
<li>
<p><code>@return </code>: is resolved as the <code>@Operation</code> response description</p>
</li>
<li>
<p>The javadoc comment of an attribute: is resolved as '@Schema' description for this field.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The projects that needs <code>Javadoc</code> support should use:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>springdoc-openapi-starter-webmvc-api</code> if they depend on <code>spring-boot-starter-web</code> and they only need the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webmvc-ui</code>, if they depend on <code>spring-boot-starter-web</code> and they also need the access to the swagger-ui.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-api</code> if they depend on <code>spring-boot-starter-webflux</code> and they only the access to the OpenAPI endpoints.</p>
</li>
<li>
<p>OR <code>springdoc-openapi-starter-webflux-ui</code>, if they depend on <code>spring-boot-starter-webflux</code> and they also need the access to the swagger-ui.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
In addition, your project should add <a href="https://github.com/dnault/therapi-runtime-javadoc"><code>therapi-runtime-javadoc</code></a> to read Javadoc comments at runtime.
Ensure that you add it as well as its annotation processor to your project’s dependencies. Otherwise, the Javadoc support will fail silently.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> <!--Annotation processor -->
<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>
<!-- Runtime library -->
<dependency>
<groupId>com.github.therapi</groupId>
<artifactId>therapi-runtime-javadoc</artifactId>
<version>0.15.0</version>
</dependency></code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If both a swagger-annotation description and a javadoc comment are present. The value of the swagger-annotation description will be used.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-11-26 16:21:53 +0100
</div>
</div>
</div>
</div>
</div>
</body>
</html>