pkp/pkp-lib#8844 Add decision request body examples to API docs

schemas/decision.json

@@ -18,7 +18,7 @@
 		},
 		"actions": {
 			"type": "array",
-			"description": "A list of actions to be taken with this decision, such as sending an email. Each decision supports different actions with different properties. See the examples for support decision actions.",
+			"description": "Optional. A list of actions to be taken with this decision, such as sending an email. Each decision supports different actions. See the request body examples for supported decision actions.",
 			"writeOnly": true,
 			"items": {
 				"type": "object"
@@ -27,25 +27,27 @@
 		"dateDecided": {
 			"type": "string",
 			"description": "The date the decision was taken.",
+			"writeDisabledInApi": true,
 			"apiSummary": true,
 			"validation": [
 				"date_format:Y-m-d H:i:s"
 			]
 		},
 		"decision": {
 			"type": "integer",
-			"description": "The decision that was made. One of the `SUBMISSION_EDITOR_DECISION_` constants.",
+			"description": "The decision that was made. One of the `Decision::*` constants.",
 			"apiSummary": true
 		},
 		"description": {
 			"type": "string",
-			"description": "A description of this decision type.",
+			"description": "A user-facing description of this decision type.",
 			"apiSummary": true,
 			"readOnly": true
 		},
 		"editorId": {
 			"type": "integer",
 			"description": "The user id of the editor who took the decision.",
+			"writeDisabledInApi": true,
 			"apiSummary": true
 		},
 		"id": {
@@ -61,20 +63,21 @@
 		},
 		"reviewRoundId": {
 			"type": "integer",
-			"description": "The unique id of the review round when this decision was taken. This is a globally unique id. It does not represent whether the decision was taken in the first or second round of reviews for a submission. See `round` below.",
+			"description": "The unique id of the review round when this decision was taken. Do not include this if the decision is not recorded in a review stage. This is a globally unique id. It does not represent whether the decision was taken in the first or second round of reviews for a submission. See `round` below.",
 			"apiSummary": true,
 			"validation": [
 				"nullable"
 			]
 		},
 		"round": {
 			"type": "integer",
-			"description": "The sequential review round when this decision was taken. For example, the first, second or third round of review for this submission.",
+			"description": "The sequential review round when this decision was taken. For example, the first, second or third round of review for this submission. Do not include this unless using `reviewRoundId`.",
 			"apiSummary": true
 		},
 		"stageId": {
 			"type": "integer",
 			"description": "The workflow stage when this decision was taken. One of the `WORKFLOW_STAGE_ID_` constants.",
+			"writeDisabledInApi": true,
 			"apiSummary": true,
 			"validation": [
 				"min:1",
@@ -84,6 +87,7 @@
 		"submissionId": {
 			"type": "integer",
 			"description": "The decision applies to this submission.",
+			"writeDisabledInApi": true,
 			"apiSummary": true
 		}
 	}

tools/buildSwagger.php

@@ -14,7 +14,12 @@
  *  documentation.
  */
 
+use APP\core\Application;
 use APP\core\Services;
+use APP\facades\Repo;
+use PKP\decision\DecisionType;
+use PKP\file\FileManager;
+use PKP\submission\reviewRound\ReviewRound;
 
 define('APP_ROOT', dirname(__FILE__, 4));
 require(APP_ROOT . '/tools/bootstrap.php');
@@ -60,8 +65,9 @@ public function execute()
             exit;
         } else {
             $source = file_get_contents(APP_ROOT . '/docs/dev/swagger-source.json');
-            if (!$source) {
-                $this->usage();
+            $decisions = file_get_contents(APP_ROOT . '/docs/dev/swagger-source-decision-examples.json');
+            if (!$source || !$decisions) {
+                echo 'Unable to find source files at ' . APP_ROOT . '/docs/dev/';
                 exit;
             }
 
@@ -189,6 +195,8 @@ public function execute()
                 }
             }
 
+            $this->addDecisionExamples($apiSchema, json_decode($decisions));
+
             file_put_contents($this->outputFile, json_encode($apiSchema, JSON_PRETTY_PRINT));
 
             echo "Done\n";
@@ -217,6 +225,90 @@ protected function setEnum(array $definition): array
 
         return $definition;
     }
+
+    /**
+     * Add the example request bodies for each decision
+     */
+    protected function addDecisionExamples(stdClass $schema, stdClass $decisions): void
+    {
+        $examples = [];
+        foreach ($decisions as $class => $decision) {
+            /** @var DecisionType $object */
+            $object = new $class();
+
+            $value = [
+                'decision' => $object->getDecision(),
+            ];
+
+            if ($this->isDecisionInReview($object)) {
+                $value['reviewRound'] = 123;
+                $value['round'] = 1;
+            }
+
+            if (!empty($decision->actions)) {
+                $value['actions'] = array_map(
+                    function(stdClass $action) {
+                        if ($action->type === 'form') {
+                            return array_merge((array) $action->data, ['id' => $action->id]);
+                        } elseif ($action->type === 'email') {
+                            return [
+                                'attachments' => [
+                                    [
+                                        'name' => 'example-upload.pdf',
+                                        'temporaryFileId' => 1,
+                                        'documentType' => FileManager::DOCUMENT_TYPE_PDF
+                                    ],
+                                    [
+                                        'name' => 'example-submission-file.pdf',
+                                        'submissionFileId' => 1,
+                                        'documentType' => FileManager::DOCUMENT_TYPE_PDF
+                                    ],
+                                    [
+                                        'name' => 'example-library-file.pdf',
+                                        'libraryFileId' => 1,
+                                        'documentType' => FileManager::DOCUMENT_TYPE_PDF
+                                    ]
+                                ],
+                                'bcc' => 'example@pkp.sfu.ca',
+                                'cc' => 'example@pkp.sfu.ca',
+                                'id' => $action->id,
+                                'locale' => 'en',
+                                'recipients' => $action->canChangeRecipients
+                                    ? [1,2]
+                                    : [],
+                                'subject' => 'Example email subject',
+                                'body' => '<p>Example email body.</p>',
+                            ];
+                        }
+                        throw new Exception('Unrecognized decision action type. Can not compile example request body for decisition ' . $class);
+                    },
+                    $decision->actions ?? []
+                );
+            }
+
+            $examples[$class] = [
+                'summary' => $object->getLabel(),
+                'value' => $value,
+            ];
+        }
+
+        $schema
+            ->paths
+            ->{'/submissions/{submissionId}/decisions'}
+            ->post
+            ->requestBody
+            ->content
+            ->{'application/json'}
+            ->examples = $examples;
+    }
+
+    /**
+     * Is the decision type in a review stage?
+     */
+    protected function isDecisionInReview(DecisionType $decision): bool
+    {
+        return in_array($decision->getStageId(), [WORKFLOW_STAGE_ID_INTERNAL_REVIEW, WORKFLOW_STAGE_ID_EXTERNAL_REVIEW]);
+    }
 }
 
 $tool = new buildSwagger($argv ?? []);