Filters in the route Spec are easy to confuse

Is your feature request related to a problem? Please describe. As a beginner user, I confused pre- and post- filters. The Spec builder API feels like it is a builder, but, in fact, it depends on the order.

From looking at the following, it is hard to answer “does it work the same?”:

r
        .method(HttpMethod.PUT)
        .filters(f -> f.filter(myFilter))
        .uri("http://mytarget/");

vs:

r
        .method(HttpMethod.PUT)
        .uri("http://mytarget/")
        .filter(myFilter);

Describe the solution you’d like I suggest renaming the methods, so that it becomes:

r
        .method(HttpMethod.PUT)
        .preFilters(f -> f.filter(requireAccessTokenFilter))
        .uri("http://mytarget/")
        .postFilter(removeOriginHeadersFiltler);

Describe alternatives you’ve considered None at the moment.

Additional context This is a follow of #1645.

[spencergibb]

I have a fix, but it is a breaking change since the javadsl is leaky and returns a builder from outside the dsl.

[spencergibb]

never mind, the fact that there is a .filter() method after .uri() is the oddity, it should be a terminal builder method (maybe?). You should use .filters(f -> {}) after the predicate.