Add response description

Proposal: I added a new method to RestGenerator which checks for response information in the REST resources's plugin definition.
This makes it possible to define the response info in the custom REST resources.

Example (in your REST resource class):

public function getPluginDefinition() {
  $definition = parent::getPluginDefinition();
  $definition['responses'] = [
    Response::HTTP_OK => [
      'description' => Response::$statusTexts[Response::HTTP_OK],
      'properties' => [
        'button_text' => [
          'type' => 'string',
          'example' => 'some text',
        ],
        'link' => [
          'type' => 'string',
          'example' => 'https://some-link.com',
        ],
      ],
    ],
    Response::HTTP_BAD_REQUEST => [
      'description' => Response::$statusTexts[Response::HTTP_BAD_REQUEST],
      'properties' => [
        'error' => [
          'type' => 'string',
          'example' => 'Received wrong request body!',
        ],
      ],
    ],
  ];

  return $definition;
}

Theoretically, you could also define it in the RestResource annotation.

/**
 * Provides REST API endpoint for a test case.
 *
 * @RestResource(
 *   id = "resource_test_case",
 *   label = @Translation("Test case resource"),
 *   uri_paths = {
 *     "canonical" = "/api/test-case"
 *   },
 *   responses = {
 *     200 = {
 *        "description" = "OK"
 *     },
 *     404 = {
 *        "description" = "Not found"
 *     }
 *   }
 * )
 */

This is just a proposal. Maybe there is a better solution?!

I have updated the patch so that the developer has full control in the plugin definition method.

Example usage:

public function getPluginDefinition() {
  return NestedArray::mergeDeep(
    parent::getPluginDefinition(),
    [
      'responses' => [
        Response::HTTP_OK => [
          'description' => Response::$statusTexts[Response::HTTP_OK],
          'schema' => [
            'type' => 'object',
            'properties' => [
              'button_text' => [
                'type' => 'string',
                'example' => 'some text',
              ],
              'link' => [
                'type' => 'string',
                'example' => 'https://some-link.com',
              ],
            ],
          ],
        ],
        Response::HTTP_BAD_REQUEST => [
          'description' => Response::$statusTexts[Response::HTTP_BAD_REQUEST],
        ],
      ],
    ]
  );
}