diff --git a/doc/ring/openapi.md b/doc/ring/openapi.md
index 34536048..98ee4e71 100644
--- a/doc/ring/openapi.md
+++ b/doc/ring/openapi.md
@@ -29,7 +29,7 @@ Coercion keys also contribute to the docs:
 
 Use `:request` parameter coercion (instead of `:body`) to unlock per-content-type coercions. See [Coercion](coercion.md).
 
-## Swagger spec
+## OpenAPI spec
 
 Serving the OpenAPI specification is handled by `reitit.openapi/create-openapi-handler`. It takes no arguments and returns a ring handler which collects at request-time data from all routes and returns an OpenAPI specification as Clojure data, to be encoded by a response formatter.
 
@@ -48,6 +48,6 @@ If you need to post-process the generated spec, just wrap the handler with a cus
 
 ## Swagger-ui
 
-[Swagger-ui](https://github.com/swagger-api/swagger-ui) is a user interface to visualize and interact with the Swagger specification. To make things easy, there is a pre-integrated version of the swagger-ui as a separate module.
+[Swagger-UI](https://github.com/swagger-api/swagger-ui) is a user interface to visualize and interact with the Swagger specification. To make things easy, there is a pre-integrated version of the swagger-ui as a separate module.
 
-- TIP: downgrade to 3.0.0 if needed
+As of Swagger-UI 4.17, OpenAPI 3.1 is not yet supported. However, most OpenAPI specs generated by reitit are also OpenAPI 3.0 compatible. You can overwrite the version string in the spec to 3.0.0, and you'll be able to use Swagger-UI. See [the http-swagger example](../../examples/http-swagger).