diff --git a/api/pom.xml b/api/pom.xml
index bf7ed935..466875d4 100644
--- a/api/pom.xml
+++ b/api/pom.xml
@@ -25,7 +25,7 @@
 
     <artifactId>microprofile-openapi-api</artifactId>
     <name>MicroProfile OpenAPI API</name>
-    <description>MicroProfile OpenAPI API :: API</description>
+    <description>MicroProfile OpenAPI :: API</description>
 
     <dependencies>
         <dependency>
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java
index bd65ccfd..6f666036 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java
@@ -46,14 +46,14 @@
  * }
  * </pre>
  * <p>
- * When this annotation is applied to a Jakarta REST resource class, the response is added to the responses defined in all
- * OpenAPI operations which correspond to a method on that class. If an operation already has a response with the
+ * When this annotation is applied to a Jakarta REST resource class, the response is added to the responses defined in
+ * all OpenAPI operations which correspond to a method on that class. If an operation already has a response with the
  * specified responseCode the response is not added to that operation.
  *
  * <p>
  * When this annotation is applied to an <code>ExceptionMapper</code> class or <code>toResponse</code> method, it allows
- * developers to describe the API response that will be added to a generated OpenAPI operation based on a Jakarta REST method
- * that declares an <code>Exception</code> of the type handled by the <code>ExceptionMapper</code>.
+ * developers to describe the API response that will be added to a generated OpenAPI operation based on a Jakarta REST
+ * method that declares an <code>Exception</code> of the type handled by the <code>ExceptionMapper</code>.
  *
  * <pre>
  * &#64;Provider
diff --git a/spi/pom.xml b/spi/pom.xml
index c9e7e865..8ab4eeaa 100644
--- a/spi/pom.xml
+++ b/spi/pom.xml
@@ -25,7 +25,13 @@
 
     <artifactId>microprofile-openapi-spi</artifactId>
     <name>MicroProfile OpenAPI SPI</name>
-    <description>MicroProfile OpenAPI SPI :: SPI</description>
+    <description>
+        MicroProfile OpenAPI :: SPI
+
+        This module is deprecated and will be removed in a future release of MicroProfile
+        OpenAPI. The functionality offered by this module is available in the microprofile-openapi-api
+        module which should be used instead.
+    </description>
 
     <dependencies>
         <dependency>
@@ -37,6 +43,4 @@
             <artifactId>microprofile-openapi-api</artifactId>
         </dependency>
     </dependencies>
-
-    
 </project>
diff --git a/spi/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java b/spi/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java
index bef662e5..c67414f3 100644
--- a/spi/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java
+++ b/spi/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java
@@ -31,7 +31,11 @@
  * Service provider for OASFactoryResolver. The implementation registers itself via the {@link java.util.ServiceLoader}
  * mechanism or by manually setting their implementation using the setInstance method.
  *
+ * @deprecated the OASFactoryResolver available in module
+ *             {@code org.eclipse.microprofile.openapi:microprofile-openapi-api} should be used instead of this version
+ *             which will be removed in a future major release.
  */
+@Deprecated(forRemoval = true)
 public abstract class OASFactoryResolver {
 
     private static volatile OASFactoryResolver instance = null;
diff --git a/spi/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java b/spi/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java
index 01cc8df4..2560ea61 100644
--- a/spi/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java
+++ b/spi/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java
@@ -13,7 +13,11 @@
 
 /**
  * Service provider interface which allows vendors to set their implementations of OASFactoryResolver.
+ * <p>
+ * The {@code org.eclipse.microprofile.openapi.spi} package available in module
+ * {@code org.eclipse.microprofile.openapi:microprofile-openapi-api} should be used instead of this version which will
+ * be removed in a future major release.
  */
-
+@Deprecated(forRemoval = true)
 @org.osgi.annotation.versioning.Version("1.0")
-package org.eclipse.microprofile.openapi.spi;
\ No newline at end of file
+package org.eclipse.microprofile.openapi.spi;