chore: Add Open API descriptions for COC endpoints (#22824)

Author: david-mackessy

dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/category/CategoryOptionComboController.java

@@ -62,7 +62,10 @@
 import org.hisp.dhis.user.UserDetails;
 import org.hisp.dhis.webapi.controller.AbstractCrudController;
 import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseStatus;
@@ -116,7 +119,14 @@ public WebMessage mergeCategoryOptionCombos(@RequestBody MergeParams params)
    * @param request request
    * @return WebMessage
    */
+  @OpenApi.Description(
+      """
+      Creating a single CategoryOptionCombo is not allowed. They should be either:
+      - left to be auto-generated by the system
+      - imported through the metadata endpoint
+      """)
   @Override
+  @PostMapping(produces = APPLICATION_JSON_VALUE)
   public WebMessage postJsonObject(HttpServletRequest request) {
     return WebMessageUtils.conflict(E1129);
   }
@@ -130,10 +140,22 @@ public WebMessage postJsonObject(HttpServletRequest request) {
    * Metadata import endpoint has very different behaviour for importing {@link
    * CategoryOptionCombo}s and is not suitable for individual updates.
    */
+  @OpenApi.Description(
+      """
+      Updating a CategoryOptionCombos is restricted, only 3 fields are updatable
+      through the PUT endpoint:
+      - attributeValues
+      - code
+      - ignoreApproval
+      Metadata import has very different behaviour for importing CategoryOptionCombos and is
+      not suitable for individual updates.
+      """)
   @Override
-  public WebMessage putJsonObject(String pvUid, UserDetails currentUser, HttpServletRequest request)
+  @PutMapping(value = "/{uid}", produces = APPLICATION_JSON_VALUE)
+  public WebMessage putJsonObject(
+      @PathVariable String uid, UserDetails currentUser, HttpServletRequest request)
       throws NotFoundException, ForbiddenException, ConflictException, IOException {
-    CategoryOptionCombo persisted = getEntity(pvUid);
+    CategoryOptionCombo persisted = getEntity(uid);
     updatePermissionCheck(currentUser, persisted);
 
     CategoryOptionComboUpdateDto cocUpdate =
@@ -151,9 +173,20 @@ public WebMessage putJsonObject(String pvUid, UserDetails currentUser, HttpServl
    * Metadata import has very different behaviour for importing {@link CategoryOptionCombo}s and is
    * not suitable for individual updates.
    */
+  @OpenApi.Description(
+      """
+      Updating a CategoryOptionCombos is restricted, only 3 fields are updatable
+      through the PATCH endpoint:
+      - attributeValues
+      - code
+      - ignoreApproval
+      Metadata import has very different behaviour for importing CategoryOptionCombos and is
+      not suitable for individual updates.
+      """)
   @Override
+  @PatchMapping(value = "/{uid}", produces = APPLICATION_JSON_VALUE)
   public WebMessage patchObject(
-      String pvUid,
+      @PathVariable String uid,
       Map<String, String> rpParameters,
       UserDetails currentUser,
       HttpServletRequest request)
@@ -162,7 +195,7 @@ public WebMessage patchObject(
           ConflictException,
           IOException,
           JsonPatchException {
-    CategoryOptionCombo persisted = getEntity(pvUid);
+    CategoryOptionCombo persisted = getEntity(uid);
     updatePermissionCheck(currentUser, persisted);
 
     JsonPatch patch = jsonMapper.readValue(request.getInputStream(), JsonPatch.class);