search

carllerche / tower-web

A fast, boilerplate free, web framework for Rust
MIT License
981 stars 51 forks source link

Swagger/Open API schema generation #63

Open anderejd opened 6 years ago

anderejd commented 6 years ago

As an interface description addict I would like to open this issue early just to inject this idea into the collective consciousness of this project. It could be worth thinking about this feature and planning ahead.

BTW, I love the stated project goals described in the README :+1:

carllerche commented 6 years ago

Good thinking getting the discussion started early 👍

I'm not familiar with either API generation strategies. Could you elaborate a bit further?

One thing I would like to see is a reflection API added so that, given a resource, you can get all the methods, args, routes, etc... Perhaps, if that were available, it would be possible to build what you are suggesting.

anderejd commented 6 years ago

I'm not familiar with either API generation strategies. Could you elaborate a bit further?

High-level overview: If a webservice can provide the OpenAPI specification, all of the protocol and deserialization code on the client side can be generated from the specification in any programming language with an OpenAPI client generator. Webservice stubs can also be generated from an OpenAPI specification but that isn't as useful imho. What I'm proposing is a feature in tower-web that can generate the OpenAPI specification document describing the webservice defined by the routes and data structures.

I have used OpenAPI (or the older version called Swagger) in a couple of C# projects, one of the implementations for OpenAPI specification generation on the server-side can be found here: https://github.com/domaindrivendev/Swashbuckle.AspNetCore. Using this specific generator relies on runtime reflection as many other things in C# do.

One thing I would like to see is a reflection API added so that, given a resource, you can get all the methods, args, routes, etc... Perhaps, if that were available, it would be possible to build what you are suggesting.

Some kind of reflection is a must, either at compile time or at runtime. I imagine that the current macros for processing the routing attributes could be made to store this information for later use?

I have a hunch that the more declarative the tower-web API is, the easier it will be to implement an OpenAPI specification generator, e.g. if authentication were to be handled by attributes too, that might help.

Here are some related links: https://github.com/OAI/OpenAPI-Specification https://www.openapis.org/

shepmaster commented 6 years ago

processing the routing attributes could be made to store this information for later use

This may also be related to (but broader than) #27.