REST API route definition files are conceptually similar to OpenAPI spec files, but so far they use a different structure. We should make the structure more like OpenAPI files, and make use of any additional information included in these files when generation OPenAPI specs (T323786).

Note that we probably don't want to manually maintain full OpenAPI specs manually. The module definition files would be partial OpenAPI specs, with the blanks filled it by automatically generating information about supported parameters and so on.

Ideally, we'll support referencing external schema definitions, so these can easily be shared between endpoints and modules. These schemas would have to be accessible through a REST endpoint as well, so they can be used in the generated OpenAPI specs.