API spec

batch/apispec.php

@@ -41,6 +41,8 @@ class APISpec_Batch {
     /** @var bool */
     private $override_param;
     /** @var bool */
+    private $override_response;
+    /** @var bool */
     private $override_tags;
     /** @var bool */
     private $override_schema;
@@ -93,7 +95,13 @@ function __construct(Conf $conf, $arg) {
                 $s = file_get_contents_throw(safe_filename($arg["i"]));
             }
             if ($s === false || !is_object($this->j = json_decode($s))) {
-                throw new CommandLineException($arg["i"] . ": Invalid input");
+                $msg = $arg["i"] . ": Invalid input";
+                if ($this->j === null
+                    && Json::decode($s) === null
+                    && Json::last_error()) {
+                    $msg .= ": " . Json::last_error_msg();
+                }
+                throw new CommandLineException($msg);
             }
             $this->output_file = $arg["i"];
             $this->batch = true;
@@ -104,6 +112,7 @@ function __construct(Conf $conf, $arg) {
 
         $this->override_ref = isset($arg["override-ref"]);
         $this->override_param = isset($arg["override-param"]);
+        $this->override_response = isset($arg["override-response"]);
         $this->override_tags = isset($arg["override-tags"]);
         $this->override_schema = isset($arg["override-schema"]);
         $this->override_description = !isset($arg["no-override-description"]);
@@ -655,36 +664,93 @@ private function expand_response($x, $uf) {
             }
         }
 
-        $rschema = $this->resolve_common_schema("minimal_response");
-        if (!empty($bprop)) {
-            $restschema = ["type" => "object"];
-            if (!empty($breq))  {
-                $restschema["required"] = $breq;
-            }
-            $restschema["properties"] = $bprop;
-            $rschema = (object) [
-                "allOf" => [$rschema, (object) $restschema]
-            ];
-        }
+        $this->apply_response($x, $bprop, $breq);
+    }
 
-        $x->responses = (object) [
-            "200" => (object) [
-                "description" => "",
-                "content" => (object) [
-                    "application/json" => (object) [
-                        "schema" => $rschema
-                    ]
-                ]
-            ],
-            "default" => (object) [
+    private function apply_response($x, $bprop, $breq) {
+        $x->responses = $x->responses ?? (object) [];
+        $resp200 = $x->responses->{"200"} = $x->responses->{"200"} ?? (object) [];
+        if (!isset($x->responses->default)) {
+            $x->responses->default = (object) [
                 "description" => "",
                 "content" => (object) [
                     "application/json" => (object) [
                         "schema" => $this->resolve_common_schema("error_response")
                     ]
                 ]
-            ]
-        ];
+            ];
+        }
+
+        $resp200->description = $resp200->description ?? "";
+        $respc = $resp200->content = $resp200->content ?? (object) [];
+        $respj = $respc->{"application/json"} = $respc->{"application/json"} ?? (object) [];
+        $resps = $respj->{"schema"} = $respj->{"schema"} ?? $this->resolve_common_schema("minimal_response");
+
+        if (($resps->{"\$ref"} ?? null) === "#/components/schemas/minimal_response") {
+            $respstype = 0;
+        } else if (is_array($resps->allOf ?? null)
+                   && count($resps->allOf) === 2
+                   && ($resps->allof[1]->type ?? null) === "object") {
+            $respstype = 1;
+        } else {
+            $respstype = -1;
+        }
+
+        if (!$this->override_response
+            && ($respstype < 0 || ($respstype > 0 && !$bprop))) {
+            return;
+        }
+
+        if (!$bprop) {
+            if ($respstype !== 0) {
+                $respj->{"schema"} = $this->resolve_common_schema("minimal_response");
+            }
+            return;
+        }
+
+        if ($respstype <= 0) {
+            $resps = $respj->{"schema"} = (object) [
+                "allOf" => [
+                    $this->resolve_common_schema("minimal_response"),
+                    (object) ["type" => "object"]
+                ]
+            ];
+        }
+        $respb = $resps->allOf[1];
+
+        // required properties
+        if ($this->override_response) {
+            if ($breq) {
+                $respb->required = $breq;
+            } else {
+                unset($respb->required);
+            }
+        } else if ($breq) {
+            $respb->required = $respb->required ?? [];
+            foreach ($breq as $p) {
+                if (!in_array($p, $respb->required)) {
+                    $respb->required[] = $p;
+                }
+            }
+        }
+
+        // property list
+        if ($this->override_response) {
+            $respprop = $respb->properties = (object) [];
+        } else {
+            $respprop = $respb->properties = $respb->properties ?? (object) [];
+        }
+        foreach ($bprop as $k => $v) {
+            if (!isset($respprop->{$k})
+                || empty((array) $respprop->{$k})) {
+                $respprop->$k = $v;
+            } else {
+                if (($v->description ?? "") !== ""
+                    && ($respprop->{$k}->description ?? "") === "") {
+                    $respprop->{$k}->description = $v->description;
+                }
+            }
+        }
     }
 
     private function sort() {
@@ -748,6 +814,7 @@ static function make_args($argv) {
             "i:,input: =FILE Modify existing specification in FILE",
             "override-ref Overwrite conflicting \$refs in input",
             "override-param",
+            "override-response",
             "override-tags",
             "override-schema",
             "no-override-description",

devel/apidoc/comments.md

@@ -21,7 +21,7 @@ decision).
 
 # get /{p}/comment
 
-> Return the JSON representation of a comment
+> Retrieve comment
 
 The `c` parameter specifies the comment to return. If the comment exists and
 the user can view it, it will be returned in the `comment` component of the
@@ -32,7 +32,7 @@ If `c` is omitted, all viewable comments are returned in a `comments` list.
 
 # post /{p}/comment
 
-> Create, modify, or delete a comment
+> Create, modify, or delete comment
 
 The `c` parameter specifies the comment to modify. It can be a numeric comment
 ID; `new`, to create a new comment; or `response` (or a compound like

devel/apidoc/documents.md

@@ -1,8 +1,16 @@
 # get /formatcheck
 
-> Check PDF format for a document
+> Check PDF format
 
 
 # post /upload
 
-> Upload support for large documents
+> Upload file
+
+This endpoint uploads documents to the server. It is intended for large
+documents, and can upload a file over multiple requests, each containing a
+slice of the data.
+
+An upload is identified by a `token`. To start an upload, set `start=1` and do
+not include a `token` parameter. All subsequent requests must include the
+`token` returned by the server in response to the `start=1` request.

devel/apidoc/redocly.yaml

@@ -1,3 +1,7 @@
+apis:
+  core@v1:
+    root: ../../etc/openapi.json
+
 theme:
   openapi:
     schemaExpansionLevel: 3

devel/apidoc/subadmin.md

@@ -1,48 +1,48 @@
 # post /assign
 
-> Perform bulk assignments
+> Bulk assignments
 
 
 # get /{p}/decision
 
-> Return decision for submission
+> Retrieve submission decision
 
 
 # post /{p}/decision
 
-> Change decision for submission
+> Change submission decision
 
 
 # get /{p}/lead
 
-> Return discussion lead for submission
+> Retrieve submission discussion lead
 
 
 # post /{p}/lead
 
-> Change decision lead for submission
+> Change submission discussion lead
 
 
 # get /{p}/manager
 
-> Return submission administrator for submission
+> Retrieve submission administrator
 
 
 # post /{p}/manager
 
-> Change submission administrator for submission
+> Change submission administrator
 
 
 # post /{p}/reviewround
 
-> Change round for review
+> Change review round
 
 
 # get /{p}/shepherd
 
-> Return shepherd for submission
+> Retrieve submission shepherd
 
 
 # post /{p}/shepherd
 
-> Change shepherd for submission
+> Change submission shepherd

devel/apidoc/tags.md

@@ -1,33 +1,33 @@
 # get /{p}/tags
 
-> Return tags for submission
+> Retrieve submission tags
 
 
 # post /tags
 
-> Change tags for submission(s)
+> Change submission tags
 
 
 # get /alltags
 
-> Return all visible tags
+> Retrieve all visible tags
 
 
 # get /taganno
 
-> Return annotations for tag
+> Retrieve tag annotations
 
 
 # post /taganno
 
-> Change annotations for tag
+> Change tag annotations
 
 
 # get /{p}/tagmessages
 
-> Return messages related to editing tags for submission
+> Retrieve tag edit messages
 
 
 # get /{p}/votereport
 
-> Return vote analysis for submission voting tag
+> Retrieve vote analysis

etc/apifunctions.json

@@ -339,7 +339,7 @@
     {
         "name": "upload", "post": true,
         "function": "Upload_API::run",
-        "parameters": "?p ?dtype ?start ?offset ?finish ?token ?cancel ?=size ?=mimetype ?=filename ?@blob",
+        "parameters": "?p ?dtype ?start ?offset ?size ?finish ?token ?cancel ?=mimetype ?=filename ?@blob",
         "response": "token ?dtype ?filename ?mimetype ?size ?ranges ?hash ?server_progress_loaded ?server_progress_max"
 
     },