Clean up community schema docs after the community-ids contract change

src/common_swagger_api/schema/apps/categories.clj

@@ -44,7 +44,8 @@
    or any of its subcategories.")
 
 (def AppCategoryNameParam (describe String "The App Category's name"))
-(def AppCommunityGroupNameParam (describe String "The full group name of the App Community"))
+(def AppCommunityGroupNameParam
+  (describe String "The App Community's identifier: its ID, its name, or a legacy colon-delimited group path"))
 
 (defschema CategoryListingParams
   {(optional-key :public)

src/common_swagger_api/schema/apps/communities.clj

@@ -1,26 +1,21 @@
 (ns common-swagger-api.schema.apps.communities
-  (:require [common-swagger-api.schema :refer [->optional-param describe NonBlankString]]
-            [common-swagger-api.schema.metadata :refer [AvuListRequest]]
+  (:require [common-swagger-api.schema :refer [describe NonBlankString]]
+            [common-swagger-api.schema.metadata :refer [SetAvuRequest]]
             [schema.core :as s]))
 
-(def AppCommunityMetadataAddSummary "Add/Update Community Metadata AVUs")
-(def AppCommunityMetadataAddDocs
-  "Adds or updates Community Metadata AVUs on the app.
-   The authenticated user must be a community admin for every Community AVU in the request,
-   in order to add or edit this metadata.")
-
-(def AppCommunityMetadataDeleteSummary "Remove Community Metadata AVUs")
+(def AppCommunityMetadataDeleteSummary "Remove an App from Communities")
 (def AppCommunityMetadataDeleteDocs
-  "Removes the given Community AVUs associated with an app.
-   The authenticated user must be a community admin for every Community AVU in the request,
-   in order to remove those AVUs.")
+  "Removes the app from each of the given communities.
+   The authenticated user must be an admin of every community in the request.
+   A caller identifies each community by its ID in `community_ids`. The `avus`
+   list is accepted as a deprecated alternative.")
 
 (def AppCommunityAddSummary "Add an App to Communities")
 (def AppCommunityAddDocs
   "Adds the app to each of the given communities.
    The authenticated user must be an admin of every community in the request.
-   The stored tag format belongs to the service, so a caller identifies a community
-   by its ID rather than composing the value itself.")
+   A caller identifies each community by its ID in `community_ids`. The `avus`
+   list is accepted as a deprecated alternative.")
 
 (def AppCommunityDeleteSummary "Remove an App from a Community")
 (def AppCommunityDeleteDocs
@@ -34,8 +29,7 @@
 ;; required, which the service enforces -- expressing "one or the other" here
 ;; would render as an unhelpful union in the generated documentation.
 (s/defschema AppCommunityListRequest
-  (-> AvuListRequest
-      (->optional-param :avus)
+  (-> SetAvuRequest
       (assoc (s/optional-key :community_ids)
              (describe [NonBlankString] "The identifiers of the communities."))
       (describe "The communities to add the app to, or remove it from.")))