-
-
Notifications
You must be signed in to change notification settings - Fork 709
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
support OpenApi #89
Comments
I think supporting something like this would be very useful! It'd probably require adding a method to |
In my opinion, the question of whether it is a good idea for documentation of RESTful (if that is ones goal when using HTTP) services to be auto generated from source code instead of being stable across source code changes (having a decoupled lifecycle) is very debatable. My suggestion would be to steer clear of any such opinionation in a core library such as warp and have others build sth on top. This on-top library can can serve the same purpose without baking a current fashion into warp. |
I would suggest to leave filter as there are. And create a Description that takes warp::filter. You can see this https://github.com/oktal/pistache/blob/master/examples/rest_description.cc#L59 |
Also related feature: labels for endpoints let filter = warp::get().and(warp::path("book")).and(warp::param("id"));
assert_eq!("/book/{id}", filter.label()); |
Has anyone started on this? If not, I might take a swing at it in 2019. |
I've been thinking more about the design of this feature; the general approach I'm thinking of would be to have a
Presumably, this would become part of testing infrastructure; with a test like #[test]
fn api_matches_blessed() {
let expected = parse_json(include_str!("blessed_api.json")).unwrap();
assert_eq!(routes().describe().to_json_value(), expected);
} (This is the main thing I want it for, at least.)
Is there a way to create such an addon library without exposing all of warp's implementation? I think it'd make sense to feature-gate this if the performance cost is non-negligible; I'd suspect it would be though, since the
Wouldn't this require duplicating the code for each handler? i.e., documentation would live separately from code, so it'd be possible for an endpoint to start accepting XML in addition to JSON, but the programmer forgets to change |
I'm attempting to prototype something that can output JSON that can be used by OpenApi, but I'm running into problems with the pervasive use of My approach would involve impl<T, U> FilterBase for And<T, U>
...
fn describe(&self) -> Description {
Description::And(Box::new(self.first.describe()), Box::new(self.second.describe()))
}
} But in order for things like I'm inclined to think that this approach is a dead-end. |
I see somebody is working on similar solution for rocket https://github.com/GREsau/okapi |
@xoac Please check https://github.com/kdy1/rweb |
Is there a way to label the routes, like @dmexe mentioned here: #89 (comment) ? My idea is to discover which was the route that was requested and collect metrics about it. The point is that I can not use the request path because it contains ids that vary between the requests, so I can not use them as key to the aggregation. The route labels could be really useful for me, if I could get it from the response, for example. Is there any way to do that, currently? |
I tried doing this aswell and got a somewhat working fork. Since the petstore specification was mentioned in the first comment, I made one based on my fork. You can see the documentation created by the openapi file. And this is the openapi.json file created. I have not touched any existing function signatures but this required me to give up on things like
It relies on a
Regarding the API, it generally looks something like this: use warp::{get, document::{describe, document, description, response, RouteDocumentation}, filters::path::path, document};
let routes = get()
.and(path("cat"))
.and(document(description("This gets the name of a cat")))
.and(document(response(200, None)))
.map(|| "Muffin");
let docs: Vec<RouteDocumentation> = describe(&routes);
let openapi = warp::document::to_openapi(docs); Note: the OpenAPI part is currently feature-gated and can definitely be put into an external crate. A problem with this is Regarding the question on labels, this let filter = warp::get().and(path("book")).and(param());
assert_eq!("/book/{0}", describe(filter).pop().unwrap().path); should work (I haven't tried it) but unfortunately naming the parameter would require a change in the Macros like in rweb would make a lot of this much simpler. |
@HiruNya Thanks for sharing all that context to your awesome work. Is something in the way of opening a PR with your changeset against upstream? I'm very interested in this functionality to aid our API documentation needs and eager to contribute to the feature in general. |
Thanks @xla, university started so I put the fork on hold for a while but I do have time to contribute in the next few weeks. The only thing stopping me from making a PR is:
One method to address this might be by only including the bare minimum needed in warp itself and hiding them with I'm keen to hear your opinion about this. |
@HiruNya Thanks for your follow-up. See some ramblings inline.
I'm happy to take your initial draft and refactor it along the needs we discover from integration into one of our projects: radicle-dev/radicle-upstream
Started to build on top of your fork, getting some additions I needed immediately. Check the commits and let me know if any of this is off base.
Ha! After integrating against your prior work I also come to believe that the lions share of the work should happen in an external crate. If I understand correctly, you had to make some invasive changes to some of the core implementations to introspect properly. Is this avoidable, if not what is a minimum changeset going to look like to enable an external crate like A point I'm particularly keen on is to move a lot of the boilerplate into macros, they are an ideal candidate as you outlined in the example repo. Also think a tighter integration with already existing serde annotations makes a lot of sense. My proposed strategy going forward would be to start a fresh crate which provides the functionality of the |
Those look great! I've been wanting to add support for oneOf but never got around to doing it.
Yeah unfortunately since all the structs are sealed and Currently, I can think of three ways of doing this (in order from most changes to warp to least changes):
I'm interested in if you have any other ways this can be done.
I've been keeping an eye on #395 which was suggesting an external
I completely agree with this especially as it would give the fork some time to mature and hopefully stabilise - would you like to create this crate or would you rather I do it? Tomorrow I'm going to merge my fork with your fork's branch and I'll try out different ways of minimising the code in the main crate. |
Hi Guys! Do you have any updates on it? It would be an awesome feature! |
This will be a really great feature. Also waiting for news and I can help with it |
Warp with OpenAPI would be great! Please finish this work. |
We dropped OpenAPI in our server a while back it still required too much manual annotation which easily went out-of-date. There is a lot more work to be done before it an ergonomic solution is possible. Namely easier derived information from actual filter definitions and macros. |
Yeah, now that grpc-web has streaming support (with the Improbable proxy at least), we may just be using Tonic instead. |
paperclip is a wip OpenAPI tool for Rust. They currently have an actix-web plugin for generating swagger specs. I'm not sure how difficult it would be to create a warp plugin... |
Yep, that would be awesome! |
I'll just leave this here as maybe some motivation - my company is fairly open about using different languages for web API microservices. One requirement however is that all microservices must support OpenAPI so a familiar interface always exists no mater the backend technology. It makes it much easier for hooking up a client. That requirement restricts me from using something like warp which I would like to use some day! |
Hi Guys, Did you tried this crate, it works fine with AXUM, should work with Warp too. |
The site is empty, there is no any docs..... |
Wrong link , patse the correct link to here: https://docs.rs/utoipa/latest/utoipa/ |
I didn't find any rust server that support OpenApi. I think it could be supported as future and should be easy to done in warp.
I mean I write a server code and I get sth like this http://petstore.swagger.io/.
What do you think?
The text was updated successfully, but these errors were encountered: