Add parameter description

Thanks for the patch alianov!
I would recommend to name the array key 'parameters' instead of 'openapi'.
I have also optimized your patch a bit.

Example usage:

public function getPluginDefinition() {
  return NestedArray::mergeDeep(
    parent::getPluginDefinition(),
    [
      'parameters' => [
        'POST' => [
          'entityType' => [
            'name' => 'entityType',
            'description' => 'The entity type name.',
            'type' => 'string',
            'in' => 'path',
            'required' => TRUE,
          ],
        ],
        'DELETE' => [
          'entityType' => [
            'name' => 'entityType',
            'description' => 'The entity type name.',
            'type' => 'string',
            'in' => 'path',
            'required' => TRUE,
          ],
        ],
      ],
    ]
  );
}

I added a payload option. Also I renamed the array key from 'parameters' to 'route_parameters', because they are only for the route parameters (resp. 'in' => 'path').

Example usage:

public function getPluginDefinition() {
  $definition = parent::getPluginDefinition();
  // Note: Since there can only be one payload, there can only be one body parameter.
  $definition['payload'] = [
    'name' => 'body',
    'description' => 'The payload',
    'in' => 'body',
    'required' => TRUE,
    'schema' => [
      'type' => 'object',
      'properties' => [
        'username' => [
          'type' => 'string',
          'example' => 'test-username',
        ],
      ],
    ],
  ];
  $definition['route_parameters'] = [
    'POST' => [
      'entityType' => [
        'name' => 'entityType',
        'description' => 'The entity type name.',
        'type' => 'string',
        'in' => 'path',
        'required' => TRUE,
      ],
    ],
    'DELETE' => [
      'entityType' => [
        'name' => 'entityType',
        'description' => 'The entity type name.',
        'type' => 'string',
        'in' => 'path',
        'required' => TRUE,
      ],
    ],
  ];

  return $definition;
}

Hi,

It's nice to see the work already done for this so describing parameters is possible.
I do had however one use case which wasn't covered yet (could be I'm just missing documentation) but my rest resource can handle a offset query parameter.
To make sure modules like swagger_ui can handle those parameters and display them in the documentation I've added a small functionality to this generator.

Example usage:
Use 'query_params' in your rest resource.

  /**
   * {@inheritDoc}
   */
  public function getBaseRoute($canonical_path, $method) {
    $route = parent::getBaseRoute($canonical_path, $method);
    $route->setOption('query_params', [
      [
        'name' => 'offset',
        'in' => 'query',
        'type' => 'integer',
        'required' => FALSE,
        'description' => 'The page numbering, each page returns 25 items.',
      ],
    ]);
    return $route;
  }

Added simple is_array check around the extra query_params option so rest resources with paths not having any query arguments described won't throw warnings.

And now with a working patch, sorry.

I agree with #8 that the implementation in #7 does not support query parameters. However I did not like the implementation in #10 which adds a new way to specify query parameters in getBaseRoute() compared to the original implementation which does the work in the plugin definition and thus also support defining parameters in the @RestResource annotation.

I have attached an alternate approach to adding support for query parameters which is based on the work in #7. Sorry, no interdiff. For some reason it is not working.

Example usage:

public function getPluginDefinition() {
  $definition = parent::getPluginDefinition();
  // Note: Since there can only be one payload, there can only be one body parameter.
  $definition['payload'] = [
    'name' => 'body',
    'description' => 'The payload',
    'in' => 'body',
    'required' => TRUE,
    'schema' => [
      'type' => 'object',
      'properties' => [
        'username' => [
          'type' => 'string',
          'example' => 'test-username',
        ],
      ],
    ],
  ];
  $definition['route_parameters'] = [
    'POST' => [
      'entityType' => [
        'name' => 'entityType',
        'description' => 'The entity type name.',
        'type' => 'string',
        'in' => 'path',
        'required' => TRUE,
      ],
    ],
    'DELETE' => [
      'entityType' => [
        'name' => 'entityType',
        'description' => 'The entity type name.',
        'type' => 'string',
        'in' => 'path',
        'required' => TRUE,
      ],
    ],
    'GET' => [
      'offset' => [
        'name' => 'offset',
        'description' => 'The page numbering, each page returns 25 items.',
        'type' => 'integer',
        'in' => 'query',
        'required' => FALSE,
      ],
    ],
  ];

  return $definition;
}

The patch in #11 produces an invalid specification as parameters for a path must be an array. With the patch in #11 it can become an object an object when using strings for keys e.g. with offset in the example above.

The updated patch strips the keys.

The patch in #12 fails if there are no route parameters defined. Here is an updated patch which fixes that.

The Payload functionality doesn't work when it comes to different payloads per method. Modified the payload functionality to accept a nested method.

I think this should use MRs instead to make it easier for maintainers to review and merge.

I struggled for awhile trying to figure out how to specify that a param for a custom REST resource should be in the query.

I was able to do so using the patch from #15. (#14 worked for my purposes too.)

After applying the patch, I modified my @RestResource annotation to include the info about the query param like this:

/**
 * Provides a REST resource.
 *
 * @RestResource(
 *   id = "my_rest_resource",
 *   label = @Translation("My REST Reource"),
 *   uri_paths = {
 *     "create" = "/api/v1/foo/{path_param_1}/bar/{path_param_2}"
 *   },
 *   route_parameters = {
 *     "POST" = {
 *       "my_query_param" = {
 *         "name" = "my_query_param",
 *         "in" = "query",
 *         "type" = "string",
 *         "description" = "My custom query param in addition to the path params",
 *         "required" = true,
 *       }
 *     }
 *   }
 * )
 */

Setting status to Needs work for somebody to take @anybody's advice in turning this into a MR.

Sorry @immaculatexavier!
I totally missed that you had already made this a MR. :-p

MR !8 is working as well for my purpose of defining a query-based endpoint param.