Skip to content

Commit 9b69fd9

Browse files
bnasslahsenbnasslahsen
committed
Springdoc v2 with Spring 6 (without Spring Boot) . Fixes #83 
1 parent 91ade8b commit 9b69fd9

File tree

3 files changed

+288
-7
lines changed

3 files changed

+288
-7
lines changed

‎docs/faq.html

+105-1
Original file line numberDiff line numberDiff line change
@@ -1844,6 +1844,110 @@ <h3 id="_is_graalvm_supported"><a class="anchor" href="#_is_graalvm_supported"><
18441844
</div>
18451845
</div>
18461846
<div class="sect2">
1847+
<h3 id="_how_to_integrate_open_api_3_with_spring_project_not_spring_boot"><a class="anchor" href="#_how_to_integrate_open_api_3_with_spring_project_not_spring_boot"></a>How to Integrate Open API 3 with Spring project (not Spring Boot)?</h3>
1848+
<div class="paragraph">
1849+
<p>When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.</p>
1850+
</div>
1851+
<div class="paragraph">
1852+
<p>For example, lets assume you want load the swagger-ui in spring-mvc application:</p>
1853+
</div>
1854+
<div class="ulist">
1855+
<ul>
1856+
<li>
1857+
<p>You mainly, need to add the springdoc-openapi module</p>
1858+
</li>
1859+
</ul>
1860+
</div>
1861+
<div class="listingblock">
1862+
<div class="content">
1863+
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
1864+
&lt;groupId&gt;org.springdoc&lt;/groupId&gt;
1865+
&lt;artifactId&gt;springdoc-openapi-starter-webmvc-ui&lt;/artifactId&gt;
1866+
&lt;version&gt;last.version&lt;/version&gt;
1867+
&lt;/dependency&gt;</code></pre>
1868+
</div>
1869+
</div>
1870+
<div class="ulist">
1871+
<ul>
1872+
<li>
1873+
<p>If you don&#8217;t have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.version and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):</p>
1874+
</li>
1875+
</ul>
1876+
</div>
1877+
<div class="listingblock">
1878+
<div class="content">
1879+
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;dependency&gt;
1880+
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
1881+
&lt;artifactId&gt;spring-boot-autoconfigure&lt;/artifactId&gt;
1882+
&lt;version&gt;3.3.3&lt;/version&gt;
1883+
&lt;/dependency&gt;</code></pre>
1884+
</div>
1885+
</div>
1886+
<div class="ulist">
1887+
<ul>
1888+
<li>
1889+
<p>Scan for the <code>springdoc-openapi</code> 'auto-configuration classes that spring-boot automatically loads for you.</p>
1890+
</li>
1891+
<li>
1892+
<p>Depending on your module, you can find them on the file: <code>spring.factories</code> of each <code>springdoc-openapi</code> module.</p>
1893+
</li>
1894+
</ul>
1895+
</div>
1896+
<div class="listingblock">
1897+
<div class="content">
1898+
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
1899+
@EnableWebMvc
1900+
public class WebConfig implements WebApplicationInitializer {
1901+
1902+
@Override
1903+
public void onStartup(ServletContext servletContext) {
1904+
WebApplicationContext context = getContext();
1905+
servletContext.addListener(new ContextLoaderListener(context));
1906+
ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
1907+
new DispatcherServlet(context));
1908+
dispatcher.setLoadOnStartup(1);
1909+
dispatcher.addMapping("/*");
1910+
}
1911+
1912+
private AnnotationConfigWebApplicationContext getContext() {
1913+
AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
1914+
context.register(this.getClass(),
1915+
SpringDocConfiguration.class,
1916+
SpringDocConfigProperties.class,
1917+
SpringDocSpecPropertiesConfiguration.class,
1918+
SpringDocWebMvcConfiguration.class,
1919+
MultipleOpenApiSupportConfiguration.class,
1920+
SwaggerConfig.class,
1921+
SwaggerUiConfigProperties.class,
1922+
SwaggerUiOAuthProperties.class,
1923+
SpringDocUIConfiguration.class
1924+
);
1925+
return context;
1926+
}
1927+
}
1928+
</code></pre>
1929+
</div>
1930+
</div>
1931+
<div class="ulist">
1932+
<ul>
1933+
<li>
1934+
<p>Depending on your module, you can find them on the file: <code>org.springframework.boot.autoconfigure.AutoConfiguration.imports</code> of each <code>springdoc-openapi</code> module.</p>
1935+
</li>
1936+
<li>
1937+
<p>For groups usage make sure your <code>GroupedOpenApi</code> Beans are scanned.</p>
1938+
</li>
1939+
<li>
1940+
<p>If additionally, you are using custom <code>context path</code>: <code>/my-servlet-path</code>. Make sure you declare the following property:</p>
1941+
</li>
1942+
</ul>
1943+
</div>
1944+
<div class="listingblock">
1945+
<div class="content">
1946+
<pre>spring.mvc.servlet.path=/my-servlet-path</pre>
1947+
</div>
1948+
</div>
1949+
</div>
1950+
<div class="sect2">
18471951
<h3 id="_what_is_the_compatibility_matrix_of_springdoc_openapi_with_spring_boot"><a class="anchor" href="#_what_is_the_compatibility_matrix_of_springdoc_openapi_with_spring_boot"></a>What is the compatibility matrix of <code>springdoc-openapi</code> with <code>spring-boot</code> ?</h3>
18481952
<div class="paragraph">
18491953
<p><code>springdoc-openapi 2.x</code> is compatible with <code>spring-boot 3</code>.</p>
@@ -1962,7 +2066,7 @@ <h3 id="_some_parameters_are_not_generated_in_the_resulting_openapi_spec"><a cla
19622066
</div>
19632067
<div id="footer">
19642068
<div id="footer-text">
1965-
Last updated 2024-06-18 01:20:05 +0200
2069+
Last updated 2024-09-27 22:52:27 +0200
19662070
</div>
19672071
</div>
19682072
</div>

‎docs/index.html

+111-6
Original file line numberDiff line numberDiff line change
@@ -223,9 +223,10 @@ <h1>springdoc-openapi v2.6.0</h1>
223223
<li><a href="#how-can-i-define-different-description-for-a-class-attribute-depending-on-usage">13.75. How can i define different description for a class attribute depending on usage?</a></li>
224224
<li><a href="#customizing-swagger-static-resources">13.76. Customizing swagger static resources</a></li>
225225
<li><a href="#is-graalvm-supported">13.77. Is GraalVM supported ?</a></li>
226-
<li><a href="#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot">13.78. What is the compatibility matrix of <code>springdoc-openapi</code> with <code>spring-boot</code> ?</a></li>
227-
<li><a href="#why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter">13.79. Why am i getting an error: <code>Swagger UI unable to render definition</code>, when overriding the default spring registered <code>HttpMessageConverter</code>?</a></li>
228-
<li><a href="#some-parameters-are-not-generated-in-the-resulting-openapi-spec">13.80. Some parameters are not generated in the resulting OpenAPI spec.</a></li>
226+
<li><a href="#how-to-integrate-open-api-3-with-spring-project-not-spring-boot">13.78. How to Integrate Open API 3 with Spring project (not Spring Boot)?</a></li>
227+
<li><a href="#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot">13.79. What is the compatibility matrix of <code>springdoc-openapi</code> with <code>spring-boot</code> ?</a></li>
228+
<li><a href="#why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter">13.80. Why am i getting an error: <code>Swagger UI unable to render definition</code>, when overriding the default spring registered <code>HttpMessageConverter</code>?</a></li>
229+
<li><a href="#some-parameters-are-not-generated-in-the-resulting-openapi-spec">13.81. Some parameters are not generated in the resulting OpenAPI spec.</a></li>
229230
</ul>
230231
</li>
231232
</ul>
@@ -4505,7 +4506,111 @@ <h3 id="is-graalvm-supported"><a class="anchor" href="#is-graalvm-supported"></a
45054506
</div>
45064507
</div>
45074508
<div class="sect2">
4508-
<h3 id="what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot"><a class="anchor" href="#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot"></a>13.78. What is the compatibility matrix of <code>springdoc-openapi</code> with <code>spring-boot</code> ?</h3>
4509+
<h3 id="how-to-integrate-open-api-3-with-spring-project-not-spring-boot"><a class="anchor" href="#how-to-integrate-open-api-3-with-spring-project-not-spring-boot"></a>13.78. How to Integrate Open API 3 with Spring project (not Spring Boot)?</h3>
4510+
<div class="paragraph">
4511+
<p>When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.</p>
4512+
</div>
4513+
<div class="paragraph">
4514+
<p>For example, lets assume you want load the swagger-ui in spring-mvc application:</p>
4515+
</div>
4516+
<div class="ulist">
4517+
<ul>
4518+
<li>
4519+
<p>You mainly, need to add the springdoc-openapi module</p>
4520+
</li>
4521+
</ul>
4522+
</div>
4523+
<div class="listingblock">
4524+
<div class="content">
4525+
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
4526+
&lt;groupId&gt;org.springdoc&lt;/groupId&gt;
4527+
&lt;artifactId&gt;springdoc-openapi-starter-webmvc-ui&lt;/artifactId&gt;
4528+
&lt;version&gt;last.version&lt;/version&gt;
4529+
&lt;/dependency&gt;</code></pre>
4530+
</div>
4531+
</div>
4532+
<div class="ulist">
4533+
<ul>
4534+
<li>
4535+
<p>If you don&#8217;t have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.version and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):</p>
4536+
</li>
4537+
</ul>
4538+
</div>
4539+
<div class="listingblock">
4540+
<div class="content">
4541+
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;dependency&gt;
4542+
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
4543+
&lt;artifactId&gt;spring-boot-autoconfigure&lt;/artifactId&gt;
4544+
&lt;version&gt;3.3.3&lt;/version&gt;
4545+
&lt;/dependency&gt;</code></pre>
4546+
</div>
4547+
</div>
4548+
<div class="ulist">
4549+
<ul>
4550+
<li>
4551+
<p>Scan for the <code>springdoc-openapi</code> 'auto-configuration classes that spring-boot automatically loads for you.</p>
4552+
</li>
4553+
<li>
4554+
<p>Depending on your module, you can find them on the file: <code>spring.factories</code> of each <code>springdoc-openapi</code> module.</p>
4555+
</li>
4556+
</ul>
4557+
</div>
4558+
<div class="listingblock">
4559+
<div class="content">
4560+
<pre class="highlight"><code class="language-java" data-lang="java">@Configuration
4561+
@EnableWebMvc
4562+
public class WebConfig implements WebApplicationInitializer {
4563+
4564+
@Override
4565+
public void onStartup(ServletContext servletContext) {
4566+
WebApplicationContext context = getContext();
4567+
servletContext.addListener(new ContextLoaderListener(context));
4568+
ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
4569+
new DispatcherServlet(context));
4570+
dispatcher.setLoadOnStartup(1);
4571+
dispatcher.addMapping("/*");
4572+
}
4573+
4574+
private AnnotationConfigWebApplicationContext getContext() {
4575+
AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
4576+
context.register(this.getClass(),
4577+
SpringDocConfiguration.class,
4578+
SpringDocConfigProperties.class,
4579+
SpringDocSpecPropertiesConfiguration.class,
4580+
SpringDocWebMvcConfiguration.class,
4581+
MultipleOpenApiSupportConfiguration.class,
4582+
SwaggerConfig.class,
4583+
SwaggerUiConfigProperties.class,
4584+
SwaggerUiOAuthProperties.class,
4585+
SpringDocUIConfiguration.class
4586+
);
4587+
return context;
4588+
}
4589+
}
4590+
</code></pre>
4591+
</div>
4592+
</div>
4593+
<div class="ulist">
4594+
<ul>
4595+
<li>
4596+
<p>Depending on your module, you can find them on the file: <code>org.springframework.boot.autoconfigure.AutoConfiguration.imports</code> of each <code>springdoc-openapi</code> module.</p>
4597+
</li>
4598+
<li>
4599+
<p>For groups usage make sure your <code>GroupedOpenApi</code> Beans are scanned.</p>
4600+
</li>
4601+
<li>
4602+
<p>If additionally, you are using custom <code>context path</code>: <code>/my-servlet-path</code>. Make sure you declare the following property:</p>
4603+
</li>
4604+
</ul>
4605+
</div>
4606+
<div class="listingblock">
4607+
<div class="content">
4608+
<pre>spring.mvc.servlet.path=/my-servlet-path</pre>
4609+
</div>
4610+
</div>
4611+
</div>
4612+
<div class="sect2">
4613+
<h3 id="what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot"><a class="anchor" href="#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot"></a>13.79. What is the compatibility matrix of <code>springdoc-openapi</code> with <code>spring-boot</code> ?</h3>
45094614
<div class="paragraph">
45104615
<p><code>springdoc-openapi 2.x</code> is compatible with <code>spring-boot 3</code>.</p>
45114616
</div>
@@ -4563,7 +4668,7 @@ <h3 id="what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot">
45634668
</table>
45644669
</div>
45654670
<div class="sect2">
4566-
<h3 id="why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter"><a class="anchor" href="#why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter"></a>13.79. Why am i getting an error: <code>Swagger UI unable to render definition</code>, when overriding the default spring registered <code>HttpMessageConverter</code>?</h3>
4671+
<h3 id="why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter"><a class="anchor" href="#why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter"></a>13.80. Why am i getting an error: <code>Swagger UI unable to render definition</code>, when overriding the default spring registered <code>HttpMessageConverter</code>?</h3>
45674672
<div class="paragraph">
45684673
<p>When overriding the default spring-boot registered <code>HttpMessageConverter</code>, you should have <code>ByteArrayHttpMessageConverter</code> registered as well to have proper <code>springdoc-openapi</code> support.</p>
45694674
</div>
@@ -4588,7 +4693,7 @@ <h3 id="why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-ov
45884693
</div>
45894694
</div>
45904695
<div class="sect2">
4591-
<h3 id="some-parameters-are-not-generated-in-the-resulting-openapi-spec"><a class="anchor" href="#some-parameters-are-not-generated-in-the-resulting-openapi-spec"></a>13.80. Some parameters are not generated in the resulting OpenAPI spec.</h3>
4696+
<h3 id="some-parameters-are-not-generated-in-the-resulting-openapi-spec"><a class="anchor" href="#some-parameters-are-not-generated-in-the-resulting-openapi-spec"></a>13.81. Some parameters are not generated in the resulting OpenAPI spec.</h3>
45924697
<div class="paragraph">
45934698
<p>The issue is caused by the changes introduced by <a href="https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.2-Release-Notes" target="_blank" rel="noopener">Spring-Boot 3.2.0</a>
45944699
in particular for the <strong>Parameter Name Discovery</strong>.

‎src/docs/asciidoc/faq.adoc

+72
Original file line numberDiff line numberDiff line change
@@ -944,6 +944,78 @@ public class OpenAPIConfig {
944944
}
945945
----
946946

947+
=== How to Integrate Open API 3 with Spring project (not Spring Boot)?
948+
When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.
949+
950+
For example, lets assume you want load the swagger-ui in spring-mvc application:
951+
952+
* You mainly, need to add the springdoc-openapi module
953+
954+
[source,xml]
955+
----
956+
<dependency>
957+
<groupId>org.springdoc</groupId>
958+
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
959+
<version>last.version</version>
960+
</dependency>
961+
----
962+
963+
* If you don't have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.version and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):
964+
965+
[source,xml]
966+
----
967+
<dependency>
968+
<groupId>org.springframework.boot</groupId>
969+
<artifactId>spring-boot-autoconfigure</artifactId>
970+
<version>3.3.3</version>
971+
</dependency>
972+
----
973+
974+
* Scan for the `springdoc-openapi` 'auto-configuration classes that spring-boot automatically loads for you.
975+
* Depending on your module, you can find them on the file: `spring.factories` of each `springdoc-openapi` module.
976+
977+
[source,java]
978+
----
979+
@Configuration
980+
@EnableWebMvc
981+
public class WebConfig implements WebApplicationInitializer {
982+
983+
@Override
984+
public void onStartup(ServletContext servletContext) {
985+
WebApplicationContext context = getContext();
986+
servletContext.addListener(new ContextLoaderListener(context));
987+
ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
988+
new DispatcherServlet(context));
989+
dispatcher.setLoadOnStartup(1);
990+
dispatcher.addMapping("/*");
991+
}
992+
993+
private AnnotationConfigWebApplicationContext getContext() {
994+
AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
995+
context.register(this.getClass(),
996+
SpringDocConfiguration.class,
997+
SpringDocConfigProperties.class,
998+
SpringDocSpecPropertiesConfiguration.class,
999+
SpringDocWebMvcConfiguration.class,
1000+
MultipleOpenApiSupportConfiguration.class,
1001+
SwaggerConfig.class,
1002+
SwaggerUiConfigProperties.class,
1003+
SwaggerUiOAuthProperties.class,
1004+
SpringDocUIConfiguration.class
1005+
);
1006+
return context;
1007+
}
1008+
}
1009+
----
1010+
1011+
* Depending on your module, you can find them on the file: `org.springframework.boot.autoconfigure.AutoConfiguration.imports` of each `springdoc-openapi` module.
1012+
* For groups usage make sure your `GroupedOpenApi` Beans are scanned.
1013+
* If additionally, you are using custom `context path`: `/my-servlet-path`. Make sure you declare the following property:
1014+
[source,properties]
1015+
----
1016+
spring.mvc.servlet.path=/my-servlet-path
1017+
----
1018+
9471019
=== What is the compatibility matrix of `springdoc-openapi` with `spring-boot` ?
9481020
`springdoc-openapi 2.x` is compatible with `spring-boot 3`.
9491021

0 commit comments

Comments
 (0)