docs update

springdoc · Sep 27, 2024 · cf98fea · cf98fea
1 parent 97a607e
commit cf98fea
Show file tree

Hide file tree

Showing 15 changed files with 99 additions and 43 deletions.
diff --git a/docs/faq.html b/docs/faq.html
@@ -298,15 +298,13 @@ <h3 id="_how_can_i_set_swagger_properties_programmatically"><a class="anchor" hr
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
-@Bean
+<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
 @Primary
 fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
     config.showCommonExtensions = true
     config.queryConfigEnabled = true
     return config
 }
----
 </code></pre>
 </div>
 </div>
@@ -579,7 +577,7 @@ <h3 id="_how_can_i_deploy_springdoc_openapi_starter_webmvc_ui_behind_a_reverse_p
 <p>If this is not enough, Spring Framework provides a <code>ForwardedHeaderFilter</code>. You can register it as a Servlet Filter in your application by setting server.forward-headers-strategy is set to FRAMEWORK.</p>
 </li>
 <li>
-<p>Since Spring Boot 3.2, this is the new property to handle reverse proxy headers:</p>
+<p>Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:</p>
 </li>
 </ul>
 </div>
@@ -1241,8 +1239,40 @@ <h3 id="_is_file_upload_supported"><a class="anchor" href="#_is_file_upload_supp
 <li>
 <p>The library supports the main file types: <code>MultipartFile</code>,  <code>@RequestPart</code>, <code>FilePart</code></p>
 </li>
+<li>
+<p>You can upload a file as follows:</p>
+</li>
 </ul>
 </div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java"><span class="fold-block hide-when-folded">import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Encoding;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+
+</span><span class="fold-block">@PostMapping(value = "/upload", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity&lt;?&gt; upload(@Parameter(description = "file") final MultipartFile file) {
+    return null;
+}
+
+@PostMapping(value = "/uploadFileWithQuery", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity&lt;?&gt; uploadFileWithQuery(@Parameter(description = "file") @RequestPart("file") final MultipartFile file,
+        @Parameter(description = "An extra query parameter") @RequestParam String name) {
+    return null;
+}
+
+@PostMapping(value = "/uploadFileWithJson", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE}, produces = {
+        MediaType.APPLICATION_JSON_VALUE})
+public ResponseEntity&lt;?&gt; uploadFileWithJson(
+        @RequestBody(content = @Content(encoding = @Encoding(name = "jsonRequest", contentType = MediaType.APPLICATION_JSON_VALUE)))
+        @Parameter(description = "An extra JSON payload sent with file") @RequestPart("jsonRequest") final JsonRequest jsonRequest,
+        @RequestPart("file") final MultipartFile file) {
+    return null;
+}
+</span></code></pre>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="_can_i_use_parameter_inside_operation_annotation"><a class="anchor" href="#_can_i_use_parameter_inside_operation_annotation"></a>Can I use <code>@Parameter</code> inside <code>@Operation</code> annotation?</h3>
@@ -2066,7 +2096,7 @@ <h3 id="_some_parameters_are_not_generated_in_the_resulting_openapi_spec"><a cla
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-09-27 22:52:27 +0200
+Last updated 2024-09-27 22:58:30 +0200
 </div>
 </div>
 </div>

diff --git a/docs/favicon.ico b/docs/favicon.ico
diff --git a/docs/index.html b/docs/index.html
@@ -1334,7 +1334,7 @@ <h3 id="integration-with-wildfly"><a class="anchor" href="#integration-with-wild
 <h2 id="properties"><a class="anchor" href="#properties"></a>5. Springdoc-openapi Properties</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p><code>springdoc-openapi</code> relies on standard <a href="https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config" target="_blank" rel="noopener">spring configuration properties</a> (yml or properties) using the standard files locations.</p>
+<p><code>springdoc-openapi</code> relies on standard <a href="https://docs.spring.io/spring-boot/reference/features/external-config.html" target="_blank" rel="noopener">spring configuration properties</a> (yml or properties) using the standard files locations.</p>
 </div>
 <div class="sect2">
 <h3 id="springdoc-openapi-core-properties"><a class="anchor" href="#springdoc-openapi-core-properties"></a>5.1. springdoc-openapi core properties</h3>
@@ -1697,8 +1697,8 @@ <h3 id="swagger-ui-properties"><a class="anchor" href="#swagger-ui-properties"><
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="https://validator.swagger.io/validator" class="bare">validator.swagger.io/validator</a></code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI attempts to validate specs against swagger.io&#8217;s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators <a href="https://github.com/swagger-api/validator-badge" target="_blank" rel="noopener">Validator Badge</a>. Setting it to either <code>none</code>, <code>127.0.0.1</code> or <code>localhost</code> will disable validation.</p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator.</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>
@@ -2335,7 +2335,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
 <p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
 </li>
 <li>
-<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
+<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
 </li>
 <li>
 <p><code>@ApiModelProperty</code> &#8594; <code>@Schema</code></p>
@@ -2960,15 +2960,13 @@ <h3 id="how-can-i-set-swagger-properties-programmatically"><a class="anchor" hre
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
-@Bean
+<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
 @Primary
 fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
     config.showCommonExtensions = true
     config.queryConfigEnabled = true
     return config
 }
----
 </code></pre>
 </div>
 </div>
@@ -3241,7 +3239,7 @@ <h3 id="how-can-i-deploy-springdoc-openapi-starter-webmvc-ui-behind-a-reverse-pr
 <p>If this is not enough, Spring Framework provides a <code>ForwardedHeaderFilter</code>. You can register it as a Servlet Filter in your application by setting server.forward-headers-strategy is set to FRAMEWORK.</p>
 </li>
 <li>
-<p>Since Spring Boot 3.2, this is the new property to handle reverse proxy headers:</p>
+<p>Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:</p>
 </li>
 </ul>
 </div>
@@ -3903,8 +3901,40 @@ <h3 id="is-file-upload-supported"><a class="anchor" href="#is-file-upload-suppor
 <li>
 <p>The library supports the main file types: <code>MultipartFile</code>,  <code>@RequestPart</code>, <code>FilePart</code></p>
 </li>
+<li>
+<p>You can upload a file as follows:</p>
+</li>
 </ul>
 </div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java"><span class="fold-block hide-when-folded">import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Encoding;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+
+</span><span class="fold-block">@PostMapping(value = "/upload", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity&lt;?&gt; upload(@Parameter(description = "file") final MultipartFile file) {
+    return null;
+}
+
+@PostMapping(value = "/uploadFileWithQuery", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity&lt;?&gt; uploadFileWithQuery(@Parameter(description = "file") @RequestPart("file") final MultipartFile file,
+        @Parameter(description = "An extra query parameter") @RequestParam String name) {
+    return null;
+}
+
+@PostMapping(value = "/uploadFileWithJson", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE}, produces = {
+        MediaType.APPLICATION_JSON_VALUE})
+public ResponseEntity&lt;?&gt; uploadFileWithJson(
+        @RequestBody(content = @Content(encoding = @Encoding(name = "jsonRequest", contentType = MediaType.APPLICATION_JSON_VALUE)))
+        @Parameter(description = "An extra JSON payload sent with file") @RequestPart("jsonRequest") final JsonRequest jsonRequest,
+        @RequestPart("file") final MultipartFile file) {
+    return null;
+}
+</span></code></pre>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="can-i-use-parameter-inside-operation-annotation"><a class="anchor" href="#can-i-use-parameter-inside-operation-annotation"></a>13.54. Can I use <code>@Parameter</code> inside <code>@Operation</code> annotation?</h3>

diff --git a/docs/migrating-from-springfox.html b/docs/migrating-from-springfox.html
@@ -71,7 +71,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
 <p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
 </li>
 <li>
-<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
+<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
 </li>
 <li>
 <p><code>@ApiModelProperty</code> &#8594; <code>@Schema</code></p>
@@ -229,7 +229,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-06-18 01:19:18 +0200
+Last updated 2024-09-27 22:59:31 +0200
 </div>
 </div>
 </div>

diff --git a/docs/properties.html b/docs/properties.html
@@ -33,7 +33,7 @@
 <h2 id="properties"><a class="anchor" href="#properties"></a>Springdoc-openapi Properties</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p><code>springdoc-openapi</code> relies on standard <a href="https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config" target="_blank" rel="noopener">spring configuration properties</a> (yml or properties) using the standard files locations.</p>
+<p><code>springdoc-openapi</code> relies on standard <a href="https://docs.spring.io/spring-boot/reference/features/external-config.html" target="_blank" rel="noopener">spring configuration properties</a> (yml or properties) using the standard files locations.</p>
 </div>
 <div class="sect2">
 <h3 id="_springdoc_openapi_core_properties"><a class="anchor" href="#_springdoc_openapi_core_properties"></a>springdoc-openapi core properties</h3>
@@ -396,8 +396,8 @@ <h3 id="_swagger_ui_properties"><a class="anchor" href="#_swagger_ui_properties"
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="https://validator.swagger.io/validator" class="bare">https://validator.swagger.io/validator</a></code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI attempts to validate specs against swagger.io&#8217;s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators <a href="https://github.com/swagger-api/validator-badge" target="_blank" rel="noopener">Validator Badge</a>. Setting it to either <code>none</code>, <code>127.0.0.1</code> or <code>localhost</code> will disable validation.</p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator.</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>
@@ -614,7 +614,7 @@ <h3 id="_swagger_ui_properties"><a class="anchor" href="#_swagger_ui_properties"
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-06-18 01:22:46 +0200
+Last updated 2024-09-27 22:58:30 +0200
 </div>
 </div>
 </div>

diff --git a/docs/ui-properties.html b/docs/ui-properties.html
@@ -65,8 +65,8 @@
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="https://validator.swagger.io/validator" class="bare">https://validator.swagger.io/validator</a></code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI attempts to validate specs against swagger.io&#8217;s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators <a href="https://github.com/swagger-api/validator-badge" target="_blank" rel="noopener">Validator Badge</a>. Setting it to either <code>none</code>, <code>127.0.0.1</code> or <code>localhost</code> will disable validation.</p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator.</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>
@@ -280,7 +280,7 @@
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-06-18 01:17:54 +0200
+Last updated 2024-09-27 23:01:03 +0200
 </div>
 </div>
 </div>

diff --git a/docs/v1/faq.html b/docs/v1/faq.html
@@ -298,15 +298,13 @@ <h3 id="_how_can_i_set_swagger_properties_programmatically"><a class="anchor" hr
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
-@Bean
+<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
 @Primary
 fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
     config.showCommonExtensions = true
     config.queryConfigEnabled = true
     return config
 }
----
 </code></pre>
 </div>
 </div>
@@ -2016,7 +2014,7 @@ <h3 id="_why_am_i_getting_an_error_swagger_ui_unable_to_render_definition_when_o
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-06-18 01:21:05 +0200
+Last updated 2024-09-27 22:58:30 +0200
 </div>
 </div>
 </div>

diff --git a/docs/v1/index.html b/docs/v1/index.html
@@ -1586,8 +1586,8 @@ <h3 id="swagger-ui-properties"><a class="anchor" href="#swagger-ui-properties"><
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="https://validator.swagger.io/validator" class="bare">validator.swagger.io/validator</a></code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI attempts to validate specs against swagger.io&#8217;s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators <a href="https://github.com/swagger-api/validator-badge" target="_blank" rel="noopener">Validator Badge</a>. Setting it to either <code>none</code>, <code>127.0.0.1</code> or <code>localhost</code> will disable validation.</p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator.</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>
@@ -2028,7 +2028,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
 <p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
 </li>
 <li>
-<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
+<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
 </li>
 <li>
 <p><code>@ApiModelProperty</code> &#8594; <code>@Schema</code></p>
@@ -2656,15 +2656,13 @@ <h3 id="how-can-i-set-swagger-properties-programmatically"><a class="anchor" hre
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
-@Bean
+<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
 @Primary
 fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
     config.showCommonExtensions = true
     config.queryConfigEnabled = true
     return config
 }
----
 </code></pre>
 </div>
 </div>

diff --git a/docs/v1/migrating-from-springfox.html b/docs/v1/migrating-from-springfox.html
@@ -71,7 +71,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
 <p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
 </li>
 <li>
-<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
+<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
 </li>
 <li>
 <p><code>@ApiModelProperty</code> &#8594; <code>@Schema</code></p>
@@ -232,7 +232,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-06-18 01:21:28 +0200
+Last updated 2024-09-27 22:59:38 +0200
 </div>
 </div>
 </div>

diff --git a/docs/v1/properties.html b/docs/v1/properties.html
@@ -396,8 +396,8 @@ <h3 id="_swagger_ui_properties"><a class="anchor" href="#_swagger_ui_properties"
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="https://validator.swagger.io/validator" class="bare">https://validator.swagger.io/validator</a></code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI attempts to validate specs against swagger.io&#8217;s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators <a href="https://github.com/swagger-api/validator-badge" target="_blank" rel="noopener">Validator Badge</a>. Setting it to either <code>none</code>, <code>127.0.0.1</code> or <code>localhost</code> will disable validation.</p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator.</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>