diff --git a/api/pom.xml b/api/pom.xml
index beb293c3..a7508ab5 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/spi/pom.xml b/spi/pom.xml
index c9b15c2a..381eb511 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..f6597a33 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,10 @@
  * 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..03ecfb7b 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;