From 5d012bc5ec87e77852cd879f6ffabd794167cf7d Mon Sep 17 00:00:00 2001
From: Eddie Kohler <ekohler@gmail.com>
Date: Mon, 16 Sep 2024 09:32:07 -0400
Subject: [PATCH] API spec

---
 batch/apispec.php |  49 ++++++----
 etc/openapi.json  | 241 +++++++++-------------------------------------
 2 files changed, 79 insertions(+), 211 deletions(-)

diff --git a/batch/apispec.php b/batch/apispec.php
index 7b0066d0f..4913e3278 100644
--- a/batch/apispec.php
+++ b/batch/apispec.php
@@ -287,7 +287,11 @@ private function resolve_common_schema($name) {
                     "description" => "Submission ID",
                     "minimum" => 1
                 ];
-                $this->setj_schemas->$name = true;
+            } else if ($name === "rid") {
+                $this->schemas->$name = (object) [
+                    "type" => "integer",
+                    "description" => "Review ID"
+                ];
             } else if ($name === "ok") {
                 return (object) ["type" => "boolean"];
             } else if ($name === "message_list") {
@@ -295,7 +299,6 @@ private function resolve_common_schema($name) {
                     "type" => "list",
                     "items" => $this->resolve_common_schema("message")
                 ];
-                $this->setj_schemas->$name = true;
             } else if ($name === "message") {
                 $this->schemas->$name = (object) [
                     "type" => "object",
@@ -309,7 +312,6 @@ private function resolve_common_schema($name) {
                         "pos2" => (object) ["type" => "integer"]
                     ]
                 ];
-                $this->setj_schemas->$name = true;
             } else if ($name === "minimal_response") {
                 $this->schemas->$name = (object) [
                     "type" => "object",
@@ -319,7 +321,6 @@ private function resolve_common_schema($name) {
                         "message_list" => $this->resolve_common_schema("message_list")
                     ]
                 ];
-                $this->setj_schemas->$name = true;
             } else if ($name === "error_response") {
                 $this->schemas->$name = (object) [
                     "type" => "object",
@@ -330,10 +331,10 @@ private function resolve_common_schema($name) {
                         "status_code" => (object) ["type" => "integer"]
                     ]
                 ];
-                $this->setj_schemas->$name = true;
             } else {
                 assert(false);
             }
+            $this->setj_schemas->$name = true;
         }
         return (object) ["\$ref" => "#/components/schemas/{$name}"];
     }
@@ -345,34 +346,40 @@ private function resolve_common_param($name) {
             $compj = $this->j->components = $this->j->components ?? (object) [];
             $this->parameters = $compj->parameters = $compj->parameters ?? (object) [];
         }
-        if (!isset($this->parameters->$name)) {
+        if (!isset($this->parameters->$name)
+            || ($this->override_schema && !isset($this->setj_parameters->$name))) {
             if ($name === "p.path") {
-                $this->parameters->{"p.path"} = (object) [
+                $this->parameters->$name = (object) [
                     "name" => "p",
                     "in" => "path",
                     "required" => true,
                     "schema" => $this->resolve_common_schema("pid")
                 ];
-                $this->setj_parameters->{"p.path"} = true;
-            } else if ($name === "p") {
-                $this->parameters->p = (object) [
+            } else if ($name === "p" || $name === "p.opt") {
+                $this->parameters->$name = (object) [
                     "name" => "p",
                     "in" => "query",
-                    "required" => false,
+                    "required" => $name === "p",
                     "schema" => $this->resolve_common_schema("pid")
                 ];
-                $this->setj_parameters->p = true;
+            } else if ($name === "r" || $name === "r.opt") {
+                $this->parameters->$name = (object) [
+                    "name" => "r",
+                    "in" => "query",
+                    "required" => $name === "r",
+                    "schema" => $this->resolve_common_schema("rid")
+                ];
             } else if ($name === "redirect") {
-                $this->parameters->redirect = (object) [
+                $this->parameters->$name = (object) [
                     "name" => "redirect",
                     "in" => "query",
                     "required" => false,
                     "schema" => (object) ["type" => "string"]
                 ];
-                $this->setj_parameters->redirect = true;
             } else {
                 assert(false);
             }
+            $this->setj_parameters->$name = true;
         }
         return (object) ["\$ref" => "#/components/parameters/{$name}"];
     }
@@ -387,10 +394,16 @@ private function expand_request($x, $known, $uf, $path) {
         foreach ($known as $name => $f) {
             if ($name === "*") {
                 // skip
-            } else if ($name === "p" && $f === (self::F_REQUIRED | self::F_PATH)) {
-                $params["p"] = $this->resolve_common_param("p.path");
             } else if ($name === "p") {
-                $params["p"] = $this->resolve_common_param("p");
+                if ($f === (self::F_REQUIRED | self::F_PATH)) {
+                    $pn = "p.path";
+                } else {
+                    $pn = $f & self::F_REQUIRED ? "p" : "p.opt";
+                }
+                $params["p"] = $this->resolve_common_param($pn);
+            } else if ($name === "r") {
+                $pn = $f & self::F_REQUIRED ? "r" : "r.opt";
+                $params["r"] = $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) {
@@ -419,7 +432,7 @@ private function expand_request($x, $known, $uf, $path) {
                 if (isset($pj->name) && is_string($pj->name)) {
                     $xparams[$pj->name] = $i;
                 } else if (isset($pj->{"\$ref"}) && is_string($pj->{"\$ref"})
-                           && preg_match('/\A\#\/components\/parameters\/([^+]*)/', $pj->{"\$ref"}, $m)) {
+                           && preg_match('/\A\#\/components\/parameters\/([^.]*)/', $pj->{"\$ref"}, $m)) {
                     $xparams[$m[1]] = $i;
                 }
             }
diff --git a/etc/openapi.json b/etc/openapi.json
index cfa9530fe..915af7a48 100644
--- a/etc/openapi.json
+++ b/etc/openapi.json
@@ -92,7 +92,7 @@
                         "schema": {}
                     },
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ],
                 "responses": {
@@ -183,7 +183,7 @@
                         "schema": {}
                     },
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ],
                 "requestBody": {
@@ -262,10 +262,10 @@
                 ],
                 "parameters": [
                     {
-                        "$ref": "#/components/parameters/redirect"
+                        "$ref": "#/components/parameters/p.opt"
                     },
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/redirect"
                     }
                 ],
                 "requestBody": {
@@ -316,12 +316,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -370,12 +364,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -444,12 +432,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -498,12 +480,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -572,12 +548,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -626,12 +596,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -700,12 +664,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -740,12 +698,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -794,12 +746,6 @@
                     "Submission administration"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -1359,12 +1305,6 @@
                     "Tags"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -1496,7 +1436,7 @@
                 },
                 "parameters": [
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ]
             }
@@ -1623,12 +1563,6 @@
                     "Tags"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -1684,12 +1618,6 @@
                         "in": "query",
                         "required": true,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "responses": {
@@ -1745,12 +1673,6 @@
                         "in": "query",
                         "required": false,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "responses": {
@@ -1806,12 +1728,6 @@
                         "in": "query",
                         "required": false,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "requestBody": {
@@ -1879,12 +1795,6 @@
                     "Reviews"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -1917,12 +1827,6 @@
                     "Reviews"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -1957,12 +1861,6 @@
                     "Reviews"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     }
@@ -1997,23 +1895,14 @@
                     "Reviews"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/redirect"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "name": "r",
-                        "in": "query",
-                        "required": true,
-                        "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
+                        "$ref": "#/components/parameters/r"
                     },
                     {
-                        "$ref": "#/components/parameters/p.path"
+                        "$ref": "#/components/parameters/redirect"
                     }
                 ],
                 "responses": {
@@ -2065,13 +1954,7 @@
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "$ref": "#/components/parameters/redirect"
-                    },
-                    {
-                        "name": "r",
-                        "in": "query",
-                        "required": true,
-                        "schema": {}
+                        "$ref": "#/components/parameters/r"
                     },
                     {
                         "name": "email",
@@ -2080,10 +1963,7 @@
                         "schema": {}
                     },
                     {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
+                        "$ref": "#/components/parameters/redirect"
                     }
                 ],
                 "responses": {
@@ -2131,23 +2011,14 @@
                     "Reviews"
                 ],
                 "parameters": [
-                    {
-                        "$ref": "#/components/parameters/redirect"
-                    },
                     {
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "name": "r",
-                        "in": "query",
-                        "required": true,
-                        "schema": {}
+                        "$ref": "#/components/parameters/r"
                     },
                     {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
+                        "$ref": "#/components/parameters/redirect"
                     }
                 ],
                 "requestBody": {
@@ -2219,12 +2090,6 @@
                         "in": "query",
                         "required": false,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "requestBody": {
@@ -2297,16 +2162,7 @@
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "name": "r",
-                        "in": "query",
-                        "required": true,
-                        "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
+                        "$ref": "#/components/parameters/r"
                     }
                 ],
                 "responses": {
@@ -2352,16 +2208,7 @@
                         "$ref": "#/components/parameters/p.path"
                     },
                     {
-                        "name": "r",
-                        "in": "query",
-                        "required": true,
-                        "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
+                        "$ref": "#/components/parameters/r"
                     }
                 ],
                 "requestBody": {
@@ -2487,12 +2334,6 @@
                         "in": "query",
                         "required": true,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "responses": {
@@ -2553,12 +2394,6 @@
                         "in": "query",
                         "required": false,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "requestBody": {
@@ -2683,7 +2518,7 @@
                 },
                 "parameters": [
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ]
             }
@@ -2707,7 +2542,7 @@
                         "schema": {}
                     },
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ],
                 "requestBody": {
@@ -2868,7 +2703,7 @@
                         "schema": {}
                     },
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ],
                 "responses": {
@@ -3015,7 +2850,7 @@
                 },
                 "parameters": [
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ]
             }
@@ -3090,12 +2925,6 @@
                         "in": "query",
                         "required": false,
                         "schema": {}
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
-                    },
-                    {
-                        "$ref": "#/components/parameters/p.path"
                     }
                 ],
                 "requestBody": {
@@ -3166,10 +2995,7 @@
                         "schema": {}
                     },
                     {
-                        "name": "r",
-                        "in": "query",
-                        "required": false,
-                        "schema": {}
+                        "$ref": "#/components/parameters/r.opt"
                     },
                     {
                         "name": "email",
@@ -3226,7 +3052,7 @@
                         "schema": {}
                     },
                     {
-                        "$ref": "#/components/parameters/p"
+                        "$ref": "#/components/parameters/p.opt"
                     }
                 ],
                 "responses": {
@@ -4040,11 +3866,36 @@
                 "schema": {
                     "$ref": "#/components/schemas/pid"
                 }
+            },
+            "r": {
+                "name": "r",
+                "in": "query",
+                "required": true,
+                "schema": {
+                    "$ref": "#/components/schemas/rid"
+                }
+            },
+            "p.opt": {
+                "name": "p",
+                "in": "query",
+                "required": false,
+                "schema": {
+                    "$ref": "#/components/schemas/pid"
+                }
+            },
+            "r.opt": {
+                "name": "r",
+                "in": "query",
+                "required": false,
+                "schema": {
+                    "$ref": "#/components/schemas/rid"
+                }
             }
         },
         "schemas": {
             "pid": {
                 "type": "integer",
+                "description": "Submission ID",
                 "minimum": 1
             },
             "message": {
@@ -4112,6 +3963,10 @@
                         "type": "integer"
                     }
                 }
+            },
+            "rid": {
+                "type": "integer",
+                "description": "Review ID"
             }
         }
     },