WIP: support for generating OpenAPI (Swagger) spec

[bluejekyll]

I'm working on some stuff to start extracting OpenAPI/Swagger specs from a configured Rocket. This is the first thing I noticed I need access to. I marked it as hidden, as it appears that you want to keep in private in case of API flux.

[bluejekyll]

FYI: here's the crate I'm working on: https://github.com/bluejekyll/rocket-openapi

[bluejekyll]

I added the function name to the route configuration so that it can be used for the operationId in OpenAPI.

See usage here: https://github.com/bluejekyll/rocket-openapi/blob/master/src/lib.rs#L72

I'm definitely open to other ideas, if you think there's a better way than this. It does kinda suck to introduce a breaking API change...

---

Here's an option I just thought of, and it would be more extensible: Route could carry an optional reference to &'static StaticRouteInfo, inside the generated StaticRouteInfo. We could put a fixed length list of additional options that can be associated to the #[<method>("path", <additional_param=option...>)], so that tools like OpenAPI generators could be passed additional information about the method.

Thoughts?

[SergioBenitez]

This is awesome! I'm incredibly supportive of this initiative.

One challenge here is to continue to support manual routing without introducing a lot of overhead. For instance, I think it would be a bit too much to expect every manual route to also be accompanied with a StaticRouteInfo object.

One way to tackle this is to ask the question: what information do you need? What would be required to get flawless documentation? For instance, why do you need the 'get_param_indexes' method to be public? I can't imagine how that's useful, but maybe you can enlighten me.

I've given some thought about how we might generate "perfect" documentation from a Rocket application. Thus far, I'm leaning towards a rustdoc-like solution with a pluggable back-end. The tool would read the application source, pulling out all of the information, including things like docstrings, and compile it all together. This would give us all of the information while being ergonomic and not imposing any overhead on the existing design. The drawback, of course, is that it's an external tool that needs to be run separately. Anyway, just my thoughts on this thus far.

[bluejekyll]

One way to tackle this is to ask the question: what information do you need? What would be required to get flawless documentation? For instance, why do you need the 'get_param_indexes' method to be public? I can't imagine how that's useful, but maybe you can enlighten me.

There are a few details that we currently don't have access to at runtime. This initial attempt was to see how far I could get with a runtime based solution, driving just off the data already generated by the rocket_codegen tools.

In terms of need, here's what I have so far:

• uri: this comes Route.uri: https://github.com/bluejekyll/rocket-openapi/blob/master/src/lib.rs#L39
• params: this is where I'm reusing get_param_indexes, it would be nice to get the type information here which I'm not doing now: https://github.com/bluejekyll/rocket-openapi/blob/master/src/lib.rs#L42
• operation_id: why I wanted access to StaticRouteInfo for the function name: https://github.com/bluejekyll/rocket-openapi/blob/master/src/lib.rs#L72
• produces and consumes: I'm generating this from Route.format: https://github.com/bluejekyll/rocket-openapi/blob/master/src/lib.rs#L73

Here are the gaps that we still need, and probably require additional and possibly separate code generators:

• responses: here we need json-schema for all the return types of the Rocket routes. It would be interesting to somehow use the Responder type to get at some of this information. I started looking at the serde tools to see if there was something that already does this, but didn't find anything (yet?).
• body parameters: again json-schema for post/patch/put data.
• description: it would be nice to pull this from doc headers, like you suggest, and assuming people generally follow the Rust rfcs for parameter docs on functions, then we could extract description for the params as well.

On top of that there are many other options that can be defined in openapi... but I think these are the required ones.

I've given some thought about how we might generate "perfect" documentation from a Rocket application. Thus far, I'm leaning towards a rustdoc-like solution with a pluggable back-end.

I think this is a great idea! In terms of Swagger/OpenAPI, many apps host the swagger UI on an endpoint on the webapp for easy browsing. So as long as that would be supported, I think it would be great.

[bluejekyll]

Why don't we close this for now, and as I have time to make more progress I'll resubmit.