Spec: Clarify auth responses in the REST spec. (apache#6251)

open-api/rest-catalog-open-api.yaml

@@ -506,10 +506,10 @@ paths:
 
         The response contains both configuration and table metadata. The configuration, if non-empty is used
         as additional configuration for the table that overrides catalog configuration. For example, this
-        configuration may change the FileIO implemented used for the table.
+        configuration may change the FileIO implementation to be used for the table.
 
 
-        The response also contains the table's full metadata.
+        The response also contains the table's full metadata, matching the table metadata JSON file.
 
 
         The catalog configuration may contain credentials that should be used for subsequent requests for the
@@ -2385,6 +2385,13 @@ components:
   securitySchemes:
     OAuth2:
       type: oauth2
+      description:
+        This scheme is used for OAuth2 authorization.
+
+
+        For unauthorized requests, services should return an appropriate 401 or
+        403 response. Implementations must not return altered success (200)
+        responses when a request is unauthenticated or unauthorized.
       flows:
         clientCredentials:
           tokenUrl: /v1/oauth/tokens