Derive routes (and validation?) from an OpenAPI specification?

[Stwissel]

Is your feature request motivated by a concrete problem? Please describe.

A common way to document REST style HTTP APIs is the OpenAPI 3.x specification (a.k.a. Swagger). It serves as the binding interface between clients and servers. A spec defines Methods and routes, as well as the data going in and out, so the spec (expressed in JSON or YAML) can be used to validate requests and responses.

Web Servers in other languages (e.g. Vert.x and this in Java or ExpressJS in NodeJS) allow to read the spec and generate the routes and validations.

The OpenAPI spec defines an OperationID, that can be used server side to identify an andpoint feeing the inner implementation from checking method and exact route layout.

Why this feature can't or shouldn't live outside of Rocket

OpenAPI has two mayor features: route definition and data validation. The data validation (JSON schema) probably could happen using an external package. After all validating JSON is useful beyond web servers. However the route rendering is core to a web server and is hard to separate.

Ideal Solution

Add a macro #[openapi("operationid")]. When rocket ignites specify the OpenAPi spec (file or string?) And load all the routes that have both a function and an entry in the openapi spec. When there is a mismatch in parameters (OpenAPI was edited but not fixed in rocket) throw a warning and not load the API. Allow functions to exist that are not in the OpenAPI file (to temp disable). SO function: compile at compile time, SPec load at runtime

Alternatives Considered

Use the swagger codegen to generate stubs

Additional Context

• JAVA: Vert.x OpenAPI validator and router
• JavaScript OpenAPI validator

[the10thWiz]

This is most likely best addressed as an external crate. There are several options here, depending on what you actually want.

I don't think generating routes from an openapi spec is actually useful, except as a one-off developer resource, so something like swagger might be more useful.

rocket_okapi provides at least part of what you're looking for. It's not exactly the same (it generates an openapi spec from your code), but I imagine you could extend it to validate that the schema is what you expect.

@SergioBenitez can weigh in, but I think this can be closed as not planned, since this can (and should) be implemented outside of Rocket.

[chr1st1ank]

This is most likely best addressed as an external crate. There are several options here, depending on what you actually want.

I don't think generating routes from an openapi spec is actually useful, except as a one-off developer resource, so something like swagger might be more useful.

rocket_okapi provides at least part of what you're looking for. It's not exactly the same (it generates an openapi spec from your code), but I imagine you could extend it to validate that the schema is what you expect.

@SergioBenitez can weigh in, but I think this can be closed as not planned, since this can (and should) be implemented outside of Rocket.

I think a route generator is not what is asked for. The feature request is rather the following idea:

Provided by the developer:

• openapi file
• endpoint functions condensed to the business logic

Handled by rocket automatically:

• Parameter validation
• response sanitization
• Mapping of requests to the right endpoint functions

A framework which offers this, but in Python, is: https://connexion.readthedocs.io/en/latest/

However, one could still consider to make this an add-on library instead of adding this to the core of rocket. Just for the sake of maintainability.

[SergioBenitez]

I don't believe it makes sense for us to implement this in Rocket internally, but I would be highly in favor of making any changes to Rocket to make such a thing possible or easier externally, if it isn't already. As such, I'm closing this issue, but should anyone give the idea a shot, please open any issues relevant.