Skip to content

Commit cf98fea

Browse files
bnasslahsenbnasslahsen
committed
docs update
1 parent 97a607e commit cf98fea

15 files changed

+99
-43
lines changed

‎docs/faq.html‎

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -298,15 +298,13 @@ <h3 id="_how_can_i_set_swagger_properties_programmatically"><a class="anchor" hr
298298
</div>
299299
<div class="listingblock">
300300
<div class="content">
301-
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
302-
@Bean
301+
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
303302
@Primary
304303
fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
305304
config.showCommonExtensions = true
306305
config.queryConfigEnabled = true
307306
return config
308307
}
309-
---
310308
</code></pre>
311309
</div>
312310
</div>
@@ -579,7 +577,7 @@ <h3 id="_how_can_i_deploy_springdoc_openapi_starter_webmvc_ui_behind_a_reverse_p
579577
<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>
580578
</li>
581579
<li>
582-
<p>Since Spring Boot 3.2, this is the new property to handle reverse proxy headers:</p>
580+
<p>Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:</p>
583581
</li>
584582
</ul>
585583
</div>
@@ -1241,8 +1239,40 @@ <h3 id="_is_file_upload_supported"><a class="anchor" href="#_is_file_upload_supp
12411239
<li>
12421240
<p>The library supports the main file types: <code>MultipartFile</code>, <code>@RequestPart</code>, <code>FilePart</code></p>
12431241
</li>
1242+
<li>
1243+
<p>You can upload a file as follows:</p>
1244+
</li>
12441245
</ul>
12451246
</div>
1247+
<div class="listingblock">
1248+
<div class="content">
1249+
<pre class="highlight"><code class="language-java" data-lang="java"><span class="fold-block hide-when-folded">import io.swagger.v3.oas.annotations.Parameter;
1250+
import io.swagger.v3.oas.annotations.media.Content;
1251+
import io.swagger.v3.oas.annotations.media.Encoding;
1252+
import io.swagger.v3.oas.annotations.parameters.RequestBody;
1253+
1254+
</span><span class="fold-block">@PostMapping(value = "/upload", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
1255+
public ResponseEntity&lt;?&gt; upload(@Parameter(description = "file") final MultipartFile file) {
1256+
return null;
1257+
}
1258+
1259+
@PostMapping(value = "/uploadFileWithQuery", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
1260+
public ResponseEntity&lt;?&gt; uploadFileWithQuery(@Parameter(description = "file") @RequestPart("file") final MultipartFile file,
1261+
@Parameter(description = "An extra query parameter") @RequestParam String name) {
1262+
return null;
1263+
}
1264+
1265+
@PostMapping(value = "/uploadFileWithJson", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE}, produces = {
1266+
MediaType.APPLICATION_JSON_VALUE})
1267+
public ResponseEntity&lt;?&gt; uploadFileWithJson(
1268+
@RequestBody(content = @Content(encoding = @Encoding(name = "jsonRequest", contentType = MediaType.APPLICATION_JSON_VALUE)))
1269+
@Parameter(description = "An extra JSON payload sent with file") @RequestPart("jsonRequest") final JsonRequest jsonRequest,
1270+
@RequestPart("file") final MultipartFile file) {
1271+
return null;
1272+
}
1273+
</span></code></pre>
1274+
</div>
1275+
</div>
12461276
</div>
12471277
<div class="sect2">
12481278
<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
20662096
</div>
20672097
<div id="footer">
20682098
<div id="footer-text">
2069-
Last updated 2024-09-27 22:52:27 +0200
2099+
Last updated 2024-09-27 22:58:30 +0200
20702100
</div>
20712101
</div>
20722102
</div>

‎docs/favicon.ico‎

115 KB
Binary file not shown.

‎docs/index.html‎

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1334,7 +1334,7 @@ <h3 id="integration-with-wildfly"><a class="anchor" href="#integration-with-wild
13341334
<h2 id="properties"><a class="anchor" href="#properties"></a>5. Springdoc-openapi Properties</h2>
13351335
<div class="sectionbody">
13361336
<div class="paragraph">
1337-
<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>
1337+
<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>
13381338
</div>
13391339
<div class="sect2">
13401340
<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"><
16971697
</tr>
16981698
<tr>
16991699
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
1700-
<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>
1701-
<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>
1700+
<td class="tableblock halign-left valign-top"></td>
1701+
<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>
17021702
</tr>
17031703
<tr>
17041704
<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
23352335
<p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
23362336
</li>
23372337
<li>
2338-
<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
2338+
<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
23392339
</li>
23402340
<li>
23412341
<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
29602960
</div>
29612961
<div class="listingblock">
29622962
<div class="content">
2963-
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
2964-
@Bean
2963+
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
29652964
@Primary
29662965
fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
29672966
config.showCommonExtensions = true
29682967
config.queryConfigEnabled = true
29692968
return config
29702969
}
2971-
---
29722970
</code></pre>
29732971
</div>
29742972
</div>
@@ -3241,7 +3239,7 @@ <h3 id="how-can-i-deploy-springdoc-openapi-starter-webmvc-ui-behind-a-reverse-pr
32413239
<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>
32423240
</li>
32433241
<li>
3244-
<p>Since Spring Boot 3.2, this is the new property to handle reverse proxy headers:</p>
3242+
<p>Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:</p>
32453243
</li>
32463244
</ul>
32473245
</div>
@@ -3903,8 +3901,40 @@ <h3 id="is-file-upload-supported"><a class="anchor" href="#is-file-upload-suppor
39033901
<li>
39043902
<p>The library supports the main file types: <code>MultipartFile</code>, <code>@RequestPart</code>, <code>FilePart</code></p>
39053903
</li>
3904+
<li>
3905+
<p>You can upload a file as follows:</p>
3906+
</li>
39063907
</ul>
39073908
</div>
3909+
<div class="listingblock">
3910+
<div class="content">
3911+
<pre class="highlight"><code class="language-java" data-lang="java"><span class="fold-block hide-when-folded">import io.swagger.v3.oas.annotations.Parameter;
3912+
import io.swagger.v3.oas.annotations.media.Content;
3913+
import io.swagger.v3.oas.annotations.media.Encoding;
3914+
import io.swagger.v3.oas.annotations.parameters.RequestBody;
3915+
3916+
</span><span class="fold-block">@PostMapping(value = "/upload", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
3917+
public ResponseEntity&lt;?&gt; upload(@Parameter(description = "file") final MultipartFile file) {
3918+
return null;
3919+
}
3920+
3921+
@PostMapping(value = "/uploadFileWithQuery", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
3922+
public ResponseEntity&lt;?&gt; uploadFileWithQuery(@Parameter(description = "file") @RequestPart("file") final MultipartFile file,
3923+
@Parameter(description = "An extra query parameter") @RequestParam String name) {
3924+
return null;
3925+
}
3926+
3927+
@PostMapping(value = "/uploadFileWithJson", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE}, produces = {
3928+
MediaType.APPLICATION_JSON_VALUE})
3929+
public ResponseEntity&lt;?&gt; uploadFileWithJson(
3930+
@RequestBody(content = @Content(encoding = @Encoding(name = "jsonRequest", contentType = MediaType.APPLICATION_JSON_VALUE)))
3931+
@Parameter(description = "An extra JSON payload sent with file") @RequestPart("jsonRequest") final JsonRequest jsonRequest,
3932+
@RequestPart("file") final MultipartFile file) {
3933+
return null;
3934+
}
3935+
</span></code></pre>
3936+
</div>
3937+
</div>
39083938
</div>
39093939
<div class="sect2">
39103940
<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>

‎docs/migrating-from-springfox.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
7171
<p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
7272
</li>
7373
<li>
74-
<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
74+
<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
7575
</li>
7676
<li>
7777
<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
229229
</div>
230230
<div id="footer">
231231
<div id="footer-text">
232-
Last updated 2024-06-18 01:19:18 +0200
232+
Last updated 2024-09-27 22:59:31 +0200
233233
</div>
234234
</div>
235235
</div>

‎docs/properties.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
<h2 id="properties"><a class="anchor" href="#properties"></a>Springdoc-openapi Properties</h2>
3434
<div class="sectionbody">
3535
<div class="paragraph">
36-
<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>
36+
<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>
3737
</div>
3838
<div class="sect2">
3939
<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"
396396
</tr>
397397
<tr>
398398
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
399-
<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>
400-
<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>
399+
<td class="tableblock halign-left valign-top"></td>
400+
<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>
401401
</tr>
402402
<tr>
403403
<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"
614614
</div>
615615
<div id="footer">
616616
<div id="footer-text">
617-
Last updated 2024-06-18 01:22:46 +0200
617+
Last updated 2024-09-27 22:58:30 +0200
618618
</div>
619619
</div>
620620
</div>

‎docs/ui-properties.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@
6565
</tr>
6666
<tr>
6767
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
68-
<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>
69-
<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>
68+
<td class="tableblock halign-left valign-top"></td>
69+
<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>
7070
</tr>
7171
<tr>
7272
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>
@@ -280,7 +280,7 @@
280280
</div>
281281
<div id="footer">
282282
<div id="footer-text">
283-
Last updated 2024-06-18 01:17:54 +0200
283+
Last updated 2024-09-27 23:01:03 +0200
284284
</div>
285285
</div>
286286
</div>

‎docs/v1/faq.html‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -298,15 +298,13 @@ <h3 id="_how_can_i_set_swagger_properties_programmatically"><a class="anchor" hr
298298
</div>
299299
<div class="listingblock">
300300
<div class="content">
301-
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
302-
@Bean
301+
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
303302
@Primary
304303
fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
305304
config.showCommonExtensions = true
306305
config.queryConfigEnabled = true
307306
return config
308307
}
309-
---
310308
</code></pre>
311309
</div>
312310
</div>
@@ -2016,7 +2014,7 @@ <h3 id="_why_am_i_getting_an_error_swagger_ui_unable_to_render_definition_when_o
20162014
</div>
20172015
<div id="footer">
20182016
<div id="footer-text">
2019-
Last updated 2024-06-18 01:21:05 +0200
2017+
Last updated 2024-09-27 22:58:30 +0200
20202018
</div>
20212019
</div>
20222020
</div>

‎docs/v1/index.html‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1586,8 +1586,8 @@ <h3 id="swagger-ui-properties"><a class="anchor" href="#swagger-ui-properties"><
15861586
</tr>
15871587
<tr>
15881588
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
1589-
<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>
1590-
<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>
1589+
<td class="tableblock halign-left valign-top"></td>
1590+
<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>
15911591
</tr>
15921592
<tr>
15931593
<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
20282028
<p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
20292029
</li>
20302030
<li>
2031-
<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
2031+
<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
20322032
</li>
20332033
<li>
20342034
<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
26562656
</div>
26572657
<div class="listingblock">
26582658
<div class="content">
2659-
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">---
2660-
@Bean
2659+
<pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Bean
26612660
@Primary
26622661
fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
26632662
config.showCommonExtensions = true
26642663
config.queryConfigEnabled = true
26652664
return config
26662665
}
2667-
---
26682666
</code></pre>
26692667
</div>
26702668
</div>

‎docs/v1/migrating-from-springfox.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ <h2 id="migrating-from-springfox"><a class="anchor" href="#migrating-from-spring
7171
<p><code>@ApiModel</code> &#8594; <code>@Schema</code></p>
7272
</li>
7373
<li>
74-
<p><code>@ApiModelProperty(hidden = true)</code> &#8594; <code>@Schema(accessMode = READ_ONLY)</code></p>
74+
<p><code>@ApiModelProperty(allowEmptyValue = true)</code> &#8594; <code>@Schema(nullable = true)</code></p>
7575
</li>
7676
<li>
7777
<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
232232
</div>
233233
<div id="footer">
234234
<div id="footer-text">
235-
Last updated 2024-06-18 01:21:28 +0200
235+
Last updated 2024-09-27 22:59:38 +0200
236236
</div>
237237
</div>
238238
</div>

‎docs/v1/properties.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -396,8 +396,8 @@ <h3 id="_swagger_ui_properties"><a class="anchor" href="#_swagger_ui_properties"
396396
</tr>
397397
<tr>
398398
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.validatorUrl</p></td>
399-
<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>
400-
<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>
399+
<td class="tableblock halign-left valign-top"></td>
400+
<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>
401401
</tr>
402402
<tr>
403403
<td class="tableblock halign-left valign-top"><p class="tableblock">springdoc.swagger-ui.tryItOutEnabled</p></td>

0 commit comments

Comments
 (0)