support OpenApi

[xoac]

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?

[seanmonstar]

I think supporting something like this would be very useful! It'd probably require adding a method to Filter that allows it to describe itself, and combinator filters can call inner filters to build up their "description".

[algermissen]

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.

[xoac]

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

[dmexe]

Also related feature: labels for endpoints

let filter = warp::get().and(warp::path("book")).and(warp::param("id"));
assert_eq!("/book/{id}", filter.label());

[xoac]

@dmexe It could be in test module

[remexre]

Has anyone started on this? If not, I might take a swing at it in 2019.

[remexre]

I've been thinking more about the design of this feature; the general approach I'm thinking of would be to have a Filter::describe() method that returns a fairly generic Description struct, and a separate OpenAPIFormatter or the like.

@algermissen

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.

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.)

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.

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 .describe() method should be dead code. (Actually, on second thought, I'm not sure if LLVM can dead-code-eliminate trait methods that are used in trait objects.)

@xoac

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

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 .consumes(MIME(Application, Json)) to .consumes(MIME(Application, Json), MIME(Application, Xml)))?

[hgzimmerman]

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 Copy throughout the codebase.

My approach would involve Filter getting a describe() function, which would output a tree comprised of Description enums which could then be walked to produce an OpenApi specification. Something like:

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 path() to be describable, FilterFn (or something like it) would need to gain a description field. Unfortunately, because Description couldn't implement Copy because of non-copy datastructures contained within, the resulting FilterFn also couldn't be Copy, making it out of line with the trait constraints specified in many of the return statements within the project. The constraints can be relaxed to use Clone instead, but that is a breaking change with a significant negative effect on the ergonomics of warp.

I'm inclined to think that this approach is a dead-end.

[xoac]

I see somebody is working on similar solution for rocket https://github.com/GREsau/okapi

[kdy1]

@xoac Please check https://github.com/kdy1/rweb

[fhsgoncalves]

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?

[HiruNya]

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.
This should hopefully be a good enough example of the API.

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

1. Documenting the type returned by path::param (I resorted to matching the TypeId to check whether it was a String or an Integer (or it defaults to Object))

2. Documenting the type returned by query and json (Deserialize does not give me enough type information to generate documentation on).
   This means that every field will need to be explicitly documented and so I would recommend using a derive macro in the future. (As you can see from the petstore example, it can get very verbose)

It relies on a Filter::describe(&self, route: RouteDocumentation) -> Vec<RouteDocumentation> trait method, but this has a few problems:

1. Only filters can add to the description, therefore the return/response cannot be described because a response is only created when the server is running and so it can't be described on demand.
   I initially had a DocumentedReply trait which had a describe(route: RouteDcoumentation) -> Vec<RouteDocumentation> method (that didn't take self) that sort of worked for cases where the type was guaranteed (e.g. the map function would always return a JSON, etc.) but I wasn't able to merge it into the general Reply trait due to Reply needing to be boxable which would erase the type-specific information.
2. Allocating a Vec for every filter is a bit expensive so a description shouldn't be created often. I initially had started of with a DocumentedFilter trait which let you define what output struct to use in the hopes that I could eventually switch to smallvec or some other stack based implementation but when I merged the trait into FilterBase, I was not able to define a default associated type for the trait.

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 warp::document::document always returns a Filter that implements Clone (not Copy). warp::document::explicit on the other hand returns a Filter that implements Copy if the original filter and function both implement Copy.

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 param function so the only option would be to define your own param filter method like what I did in petstore.

Macros like in rweb would make a lot of this much simpler.

[xla]

@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.