api/comment with no c parameter requests all comments

And normal response is in the `comment` component, not `cmt`.
kohler · Sep 16, 2024 · 6cfbb14 · 6cfbb14
1 parent 0d86314
commit 6cfbb14
Show file tree

Hide file tree

Showing 6 changed files with 69 additions and 17 deletions.
diff --git a/batch/apispec.php b/batch/apispec.php
@@ -364,6 +364,11 @@ private function resolve_common_schema($name) {
                     "type" => "integer",
                     "description" => "Review ID"
                 ];
+            } else if ($name === "cid") {
+                $nj = (object) [
+                    "type" => "integer",
+                    "description" => "Comment ID"
+                ];
             } else if ($name === "ok") {
                 $nj = (object) [
                     "type" => "boolean",
@@ -450,6 +455,13 @@ private function resolve_common_param($name) {
                     "required" => $name === "r",
                     "schema" => $this->resolve_common_schema("rid")
                 ];
+            } else if ($name === "c" || $name === "c.opt") {
+                $nj = (object) [
+                    "name" => "c",
+                    "in" => "query",
+                    "required" => $name === "c",
+                    "schema" => $this->resolve_common_schema("cid")
+                ];
             } else if ($name === "redirect") {
                 $nj = (object) [
                     "name" => "redirect",
@@ -489,6 +501,9 @@ private function expand_request($x, $known, $uf, $path) {
             } else if ($name === "r") {
                 $pn = $f & self::F_REQUIRED ? "r" : "r.opt";
                 $params["r"] = $this->resolve_common_param($pn);
+            } else if ($name === "c") {
+                $pn = $f & self::F_REQUIRED ? "c" : "c.opt";
+                $params["c"] = $this->resolve_common_param($pn);
             } else if ($name === "redirect" && $f === 0) {
                 $params["redirect"] = $this->resolve_common_param("redirect");
             } else if (($f & (self::F_BODY | self::F_FILE)) === 0) {

diff --git a/devel/apidoc/index.md b/devel/apidoc/index.md
@@ -2,5 +2,9 @@
 
 > HotCRP conference management software API
 
-[HotCRP](https://github.com/kohler/hotcrp/) is conference review software. It
+[HotCRP](https://github.com/kohler/hotcrp) is conference review software. It
 is open source; a supported version runs on [hotcrp.com](https://hotcrp.com/).
+
+We welcome [pull requests](https://github.com/kohler/hotcrp/pulls) that fill
+out this documentation. To request documentation for an API method, please
+open a [GitHub issue](https://github.com/kohler/hotcrp/issues).
diff --git a/etc/apifunctions.json b/etc/apifunctions.json
@@ -41,7 +41,7 @@
     {
         "name": "comment", "get": true, "paper": true,
         "function": "Comment_API::run",
-        "parameters": "c",
+        "parameters": "?c ?content",
         "response": "?comment",
         "response_deprecated": "cmt"
     },

diff --git a/etc/openapi.json b/etc/openapi.json
@@ -3,8 +3,8 @@
     "info": {
         "title": "HotCRP",
         "version": "0.1",
-        "description": "[HotCRP](https://github.com/kohler/hotcrp/) is open-source conference review\nsoftware, and runs [hotcrp.com](https://hotcrp.com/).\n",
-        "summary": "HotCRP conference view software API"
+        "description": "[HotCRP](https://github.com/kohler/hotcrp) is conference review software. It\nis open source; a supported version runs on [hotcrp.com](https://hotcrp.com/).\n\nWe welcome [pull requests](https://github.com/kohler/hotcrp/pulls) that fill\nout this documentation. To request documentation for an API method, please\nopen a [GitHub issue](https://github.com/kohler/hotcrp/issues).\n",
+        "summary": "HotCRP conference management software API"
     },
     "paths": {
         "/paper": {
@@ -2332,9 +2332,12 @@
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "name": "c",
+                        "$ref": "#/components/parameters/c.opt"
+                    },
+                    {
+                        "name": "content",
                         "in": "query",
-                        "required": true,
+                        "required": false,
                         "schema": {}
                     }
                 ],
@@ -2380,10 +2383,7 @@
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "name": "c",
-                        "in": "query",
-                        "required": true,
-                        "schema": {}
+                        "$ref": "#/components/parameters/c"
                     },
                     {
                         "name": "override",
@@ -3892,6 +3892,22 @@
                 "schema": {
                     "$ref": "#/components/schemas/rid"
                 }
+            },
+            "c.opt": {
+                "name": "c",
+                "in": "query",
+                "required": false,
+                "schema": {
+                    "$ref": "#/components/schemas/cid"
+                }
+            },
+            "c": {
+                "name": "c",
+                "in": "query",
+                "required": true,
+                "schema": {
+                    "$ref": "#/components/schemas/cid"
+                }
             }
         },
         "schemas": {
@@ -3971,6 +3987,10 @@
             "rid": {
                 "type": "integer",
                 "description": "Review ID"
+            },
+            "cid": {
+                "type": "integer",
+                "description": "Comment ID"
             }
         },
         "securitySchemes": {

diff --git a/src/api/api_comment.php b/src/api/api_comment.php
@@ -186,6 +186,16 @@ private function run_post(Qrequest $qreq, $rrd, $crow) {
 
     /** @return JsonResult */
     private function run_qreq(Qrequest $qreq) {
+        // check for all-comments request
+        $content = $qreq->is_post() || friendly_boolean($qreq->content ?? "1");
+        if (!isset($qreq->c) && !$qreq->is_post()) {
+            $comments = [];
+            foreach ($this->prow->viewable_comments($this->user) as $crow) {
+                $comments[] = $crow->unparse_json($this->user, !$content);
+            }
+            return new JsonResult(200, ["ok" => true, "comments" => $comments]);
+        }
+
         // analyze response parameter
         $c = $qreq->c ?? "";
         if ($c === "response") {
@@ -277,7 +287,8 @@ private function run_qreq(Qrequest $qreq) {
             }
         }
         if ($crow && $crow->commentId > 0) {
-            $jr["cmt"] = $crow->unparse_json($this->user);
+            $jr["comment"] = $crow->unparse_json($this->user, !$content);
+            $jr["cmt"] = $jr["comment"]; // XXX backward compat
         }
         return $jr;
     }

diff --git a/src/commentinfo.php b/src/commentinfo.php
@@ -614,8 +614,9 @@ function attachments_json($editable = false) {
         return $docs;
     }
 
-    /** @return ?object */
-    function unparse_json(Contact $viewer) {
+    /** @param bool $no_content
+     * @return ?object */
+    function unparse_json(Contact $viewer, $no_content = false) {
         if ($this->commentId !== 0
             && !$viewer->can_view_comment($this->prow, $this, true)) {
             return null;
@@ -626,7 +627,7 @@ function unparse_json(Contact $viewer) {
             return null;
         }
 
-        $cj = ["pid" => $this->prow->paperId];
+        $cj = ["object" => "comment", "pid" => $this->prow->paperId];
         if ($this->commentId !== 0) {
             $cj["cid"] = $this->commentId;
             if (($o = $this->unparse_ordinal()) !== null) {
@@ -737,14 +738,15 @@ function unparse_json(Contact $viewer) {
             $cj["modified_at_text"] = $this->conf->unparse_time_point($cj["modified_at"]);
         }
 
-        // contents
-        if ($viewer->can_view_comment_content($this->prow, $this)) {
+        // content
+        if ($no_content) {
+            // do not include content
+        } else if ($viewer->can_view_comment_content($this->prow, $this)) {
             $cj["text"] = $this->content($viewer, !$idable);
             if ($this->has_attachments()) {
                 $cj["docs"] = $this->attachments_json($cj["editable"] ?? false);
             }
         } else {
-            $cj["text"] = false;
             $cj["word_count"] = count_words($this->raw_content());
         }