Skip to content

Commit f154db1

Browse files
bnasslahsenbnasslahsen
committed
doc update
1 parent 00cbe6b commit f154db1

File tree

4 files changed

+94
-30
lines changed

4 files changed

+94
-30
lines changed

‎src/docs/asciidoc/faq.adoc‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -919,24 +919,6 @@ private Schema getFieldSchemaWithDifferentDescription(Class className, String de
919919
}
920920
----
921921

922-
=== What is the compatibility matrix of `springdoc-openapi` with `spring-boot` ?
923-
`springdoc-openapi` is compatible with `spring-boot 1` and `spring-boot 2`.
924-
925-
In general, **you should only pick the last stable version as per today {springdoc-version}.**
926-
927-
More precisely, this the exhaustive list of spring-boot versions against which `springdoc-openapi` has been built:
928-
929-
|===
930-
| spring-boot Versions | Minimum springdoc-openapi Versions
931-
|`2.6.x`, `1.5.x` | `1.6.0`+
932-
|`2.5.x`, `1.5.x` | `1.5.9`+
933-
|`2.4.x`, `1.5.x` | `1.5.0`+
934-
|`2.3.x`, `1.5.x` | `1.4.0`+
935-
|`2.2.x`, `1.5.x` | `1.2.1`+
936-
|`2.0.x`, `1.5.x` | `1.0.0`+
937-
938-
|===
939-
940922
=== Customizing swagger static resources
941923

942924
You can customize swagger documentation static resources located in `META-INF/resources/webjars/swagger-ui/{swagger.version}/`. The list of resources includes:
@@ -996,4 +978,22 @@ public class OpenApiConfig {
996978

997979
Illustrative example
998980

999-
image::images/static_content_transformation.png[Illustrative example]
981+
image::images/static_content_transformation.png[Illustrative example]
982+
983+
=== What is the compatibility matrix of `springdoc-openapi` with `spring-boot` ?
984+
`springdoc-openapi` is compatible with `spring-boot 1` and `spring-boot 2`.
985+
986+
In general, **you should only pick the last stable version as per today {springdoc-version}.**
987+
988+
More precisely, this the exhaustive list of spring-boot versions against which `springdoc-openapi` has been built:
989+
990+
|===
991+
| spring-boot Versions | Minimum springdoc-openapi Versions
992+
|`2.6.x`, `1.5.x` | `1.6.0`+
993+
|`2.5.x`, `1.5.x` | `1.5.9`+
994+
|`2.4.x`, `1.5.x` | `1.5.0`+
995+
|`2.3.x`, `1.5.x` | `1.4.0`+
996+
|`2.2.x`, `1.5.x` | `1.2.1`+
997+
|`2.0.x`, `1.5.x` | `1.0.0`+
998+
999+
|===

‎src/docs/asciidoc/modules.adoc‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -137,8 +137,8 @@ To expose the swagger-ui, on the management port, you should set
137137
[source,properties]
138138
----
139139
springdoc.use-management-port=true
140-
# This property enables the openapi and swaggerui endpoints to be exposed beneath the actuator base path.
141-
management.endpoints.web.exposure.include=openapi, swaggerui
140+
# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
141+
management.endpoints.web.exposure.include=openapi, swagger-ui
142142
----
143143

144144
Once enabled, you should also be able to see the springdoc-openapi endpoints under: (host and port depends on your settings)
@@ -154,7 +154,7 @@ Two endpoints will be available:
154154

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

157-
- `\http://serverName:managementPort/actuator/swaggerui`
157+
- `\http://serverName:managementPort/actuator/swagger-ui`
158158

159159
[source,properties]
160160
----
@@ -164,9 +164,11 @@ management.server.port=9090
164164
For the example, you should also be able to see the springdoc-openapi endpoints:
165165

166166
- `\http://serverName:9090/actuator`
167-
- `\http://serverName:9090/actuator/swaggerui`
167+
- `\http://serverName:9090/actuator/swagger-ui`
168168
- `\http://serverName:9090/actuator/openapi`
169169

170+
All the path `springdoc-openapi` properties are not applicable when `springdoc.use-management-port=true`.
171+
170172
TIP: 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.
171173

172174

@@ -183,7 +185,7 @@ Once enabled:
183185

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

186-
- `\http://serverName:managementPort/actuator/swaggerui`
188+
- `\http://serverName:managementPort/actuator/swagger-ui`
187189

188190
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:
189191

‎src/docs/asciidoc/v2/faq.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -836,6 +836,67 @@ private Schema getFieldSchemaWithDifferentDescription(Class className, String de
836836
}
837837
----
838838

839+
=== Customizing swagger static resources
840+
841+
You can customize swagger documentation static resources located in `META-INF/resources/webjars/swagger-ui/{swagger.version}/`. The list of resources includes:
842+
843+
- `index.html`
844+
- `swagger-ui-bundle.js`
845+
- `swagger-ui.css`
846+
- `swagger-ui-standalone-preset.js`
847+
- `swagger-ui.css.map`
848+
- `swagger-ui-bundle.js.map`
849+
- `swagger-ui-standalone-preset.js.map`
850+
- `favicon-32x32.png`
851+
852+
To do this, you need to extend the implementation of `SwaggerIndexPageTransformer`
853+
854+
[source,java]
855+
----
856+
public class SwaggerCodeBlockTransformer
857+
extends SwaggerIndexPageTransformer {
858+
// < constructor >
859+
@Override
860+
public Resource transform(HttpServletRequest request,
861+
Resource resource,
862+
ResourceTransformerChain transformer)
863+
throws IOException {
864+
if (resource.toString().contains("swagger-ui.css")) {
865+
final InputStream is = resource.getInputStream();
866+
final InputStreamReader isr = new InputStreamReader(is);
867+
try (BufferedReader br = new BufferedReader(isr)) {
868+
final String css = br.lines().collect(Collectors.joining());
869+
final byte[] transformedContent = css.replace("old", "new").getBytes();
870+
return new TransformedResource(resource, transformedContent);
871+
} // AutoCloseable br > isr > is
872+
}
873+
return super.transform(request, resource, transformer);
874+
}
875+
876+
}
877+
----
878+
879+
Next, add transformer `@Bean` to your `@Configuration`
880+
881+
[source,java]
882+
----
883+
@Configuration
884+
public class OpenApiConfig {
885+
@Bean
886+
public SwaggerIndexTransformer swaggerIndexTransformer(
887+
SwaggerUiConfigProperties a,
888+
SwaggerUiOAuthProperties b,
889+
SwaggerUiConfigParameters c,
890+
SwaggerWelcomeCommon d) {
891+
return new SwaggerCodeBlockTransformer(a, b, c, d);
892+
}
893+
}
894+
----
895+
896+
Illustrative example
897+
898+
image::images/static_content_transformation.png[Illustrative example]
899+
839900
=== What is the compatibility matrix of `springdoc-openapi` with `spring-boot` ?
840901
`springdoc-openapi 2.x` is compatible with `spring-boot 3`.
841902

‎src/docs/asciidoc/v2/modules.adoc‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,8 @@ To expose the swagger-ui, on the management port, you should set
8181
[source,properties]
8282
----
8383
springdoc.use-management-port=true
84-
# This property enables the openapi and swaggerui endpoints to be exposed beneath the actuator base path.
85-
management.endpoints.web.exposure.include=openapi, swaggerui
84+
# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
85+
management.endpoints.web.exposure.include=openapi, swagger-ui
8686
----
8787

8888
Once enabled, you should also be able to see the springdoc-openapi endpoints under: (host and port depends on your settings)
@@ -98,7 +98,7 @@ Two endpoints will be available:
9898

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

101-
- `\http://serverName:managementPort/actuator/swaggerui`
101+
- `\http://serverName:managementPort/actuator/swagger-ui`
102102

103103
[source,properties]
104104
----
@@ -108,11 +108,12 @@ management.server.port=9090
108108
For the example, you should also be able to see the springdoc-openapi endpoints:
109109

110110
- `\http://serverName:9090/actuator`
111-
- `\http://serverName:9090/actuator/swaggerui`
111+
- `\http://serverName:9090/actuator/swagger-ui`
112112
- `\http://serverName:9090/actuator/openapi`
113113

114-
TIP: 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.
114+
All the path `springdoc-openapi` properties are not applicable when `springdoc.use-management-port=true`.
115115

116+
TIP: 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.
116117

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

@@ -127,7 +128,7 @@ Once enabled:
127128

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

130-
- `\http://serverName:managementPort/actuator/swaggerui`
131+
- `\http://serverName:managementPort/actuator/swagger-ui`
131132

132133
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:
133134

0 commit comments

Comments
 (0)