Repository: eclipse/microprofile-open-api
Pull request #346 (2019-04-30 17:40:19)

Deprecate Scope Object in 1.x
This PR is for issue #345 
Deprecated the `Scope` object and use simple maps to represent scopes in `OAuthFlow`


Patch:
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java b/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
index 77d8751..dfeeeb2 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
@@ -310,7 +310,9 @@ public final class OASFactory {
      * This method creates a new {@link org.eclipse.microprofile.openapi.models.security.Scopes} instance.
      *
      * @return a new Scopes instance
+     * @deprecated since 1.2 use <code>Map&lt;String, String&gt;</code> for scopes instead
      */
+    @Deprecated
     public static Scopes createScopes() {
         return createObject(Scopes.class);
     }
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
index f9b5913..8557984 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
@@ -17,6 +17,8 @@
 
 package org.eclipse.microprofile.openapi.models.security;
 
+import java.util.Map;
+
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
 
@@ -143,7 +145,7 @@ public interface OAuthFlow extends Constructible, Extensible<OAuthFlow> {
      * <p>
      * This method returns the scopes property from OAuthFlow instance.
      * </p> 
-     * @return Scopes scopes
+     * @return Scopes scopes (in the future this method will instead return a <code>Map&lt;String, String&gt;</code>).
      **/
     Scopes getScopes();
 
@@ -157,6 +159,36 @@ public interface OAuthFlow extends Constructible, Extensible<OAuthFlow> {
      * </p>
      * @param scopes the available scopes for the OAuth2 security scheme
      */
+    void setScopes(Map<String, String> scopes);
+
+    /**
+     * The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This is a REQUIRED property.
+     * <p>
+     * Applies to oauth2.
+     * </p>
+     * <p>
+     * This method sets the scopes property of OAuthFlow instance to the given argument and returns the modified instance.
+     * </p>
+     * @param scopes the available scopes for the OAuth2 security scheme
+     * @return OAuthFlow instance with the set scopes property
+     */
+    default OAuthFlow scopes(Map<String, String> scopes) {
+        setScopes(scopes);
+        return this;
+    }
+
+    /**
+     * The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This is a REQUIRED property.
+     * <p>
+     * Applies to oauth2.
+     * </p>
+     * <p>
+     * This method sets the scopes property of OAuthFlow instance to the given argument.
+     * </p>
+     * @param scopes the available scopes for the OAuth2 security scheme
+     * @deprecated since 1.2 use {@link #setScopes(Map)} instead
+     */
+    @Deprecated
     void setScopes(Scopes scopes);
 
     /**
@@ -169,7 +201,9 @@ public interface OAuthFlow extends Constructible, Extensible<OAuthFlow> {
      * </p>
      * @param scopes the available scopes for the OAuth2 security scheme
      * @return OAuthFlow instance with the set scopes property
+     * @deprecated since 1.2, use {@link #scopes(Map)} instead
      */
+    @Deprecated
     default OAuthFlow scopes(Scopes scopes) {
         setScopes(scopes);
         return this;
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
index dc03b1c..af4ab4f 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
@@ -26,8 +26,10 @@ import org.eclipse.microprofile.openapi.models.Extensible;
  * Scopes is a property of OAuth Flow Object.
  * 
  * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oauthFlowObject">OAuthFlow Object</a>
+ * @deprecated a future version will remove this and replace it with a <code>Map&lt;String, String&gt;</code>, because it does not
+ * need to be extensibles
  **/
-
+@Deprecated
 public interface Scopes extends Constructible, Extensible<Scopes>, Map<String, String> {
 
     /**


Test patch:
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
index c07559d..5778da0 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
@@ -783,7 +783,17 @@ public class ModelConstructionTest extends Arquillian {
     
     @Test
     public void oAuthFlowTest() {
-        processConstructible(OAuthFlow.class);
+        final OAuthFlow o = processConstructible(OAuthFlow.class);
+        final String key = "myKey";
+        final String value = new String("myValue");
+        o.setScopes(Collections.singletonMap(key, value));
+        Map<String,String> scopes = o.getScopes().getScopes();
+        assertEquals(scopes.size(), 1, "The list is expected to contain one entry.");
+        assertTrue(scopes.containsKey("myKey"), "The map is expected to contain a 'myKey' entry.");
+        assertEquals(scopes.get(key), value, "The value corresponding to the 'myKey' is wrong.");
+        
+        o.setScopes((Map<String, String>) null);
+        assertNull(o.getScopes(), "The value is expected to be null.");
     }
     
     @Test
@@ -791,6 +801,7 @@ public class ModelConstructionTest extends Arquillian {
         processConstructible(OAuthFlows.class);
     }
     
+    @Deprecated
     @Test
     public void scopesTest() {
         final Scopes s = processConstructible(Scopes.class);