spring-fu
spring-fu copied to clipboard
spring-projects-experimental
Automated HTTP API documentation
OpenAPI: we should try https://github.com/springfox/springfox/issues/1773 which has been merged and see if functional support is ok.
Spring REST docs: we should test WebTestClient support, see https://github.com/spring-projects/spring-restdocs/issues/384.
Unfortunately, I don't think it's possible to generate an OpenAPI spec via code inspection alone when you take a functional approach. The request predicates are too free-form to be able to introspect them and generate an accurate specification. For this reason, AFAIK, SpringFox quite reasonably doesn't even try – I can't find any references to WebFlux in their code.
Indeed, but we can maybe leverage RouterFunctions.Visitor like we do for logging is order to build such OpenAPI spec. Any thoughts @poutsma?
Not sure if that is going to work. Like @wilkinsona said, the request predicates is an open set, and (unless we make the predicates aware of OpenAPI) the only thing of use for a visitor is the String representation. This is what we use for logging: all pre-defined predicates have a toString that generates useful logging information. You could theoretically parse that string representation to come up with an OpenAPI spec, but that seems very fragile.
Using a Visitor should be possible if subclass of RequestPredicate like HeadersPredicate or QueryParamPredicate were public.
Maybe Webflux framework could have another Visitor who generate a kind of RouterFunction data structure with all the RequestPredicate informations.
This kind of data structure will be used for automated API documentation.
To explain what I'm saying in my previous message, I've wrote a RouterFunctions.Visitor in spring-framework.
It's in a very early stage and provide a kind of schema for all routes with RequestPredicate :
https://github.com/spring-projects/spring-framework/compare/master...tgirard12:webflux-visitor
Since I am a big fan of Spring REST docs but also recognize the need to document REST API in a machine readable way, I think I will prototype something based on @tgirard12 RouterFunctions.Visitor approach used with https://github.com/ePages-de/restdocs-openapi mentioned in https://github.com/spring-projects/spring-restdocs/issues/213.
@tgirard12 Do you think it would be possible for you to play a little bit with the Spring Framework branch Arjen Poutsma has been working on (targeting upcoming 5.1.2, see this JIRA comment) to see if that fit the need from your POV?
I have play a little with this branch. I think it will possible to get all the RequestPredicates for all routes if we use both a RouterFunctions.Visitor and a RequestPredicates.Visitor.
The current implementation have some limitations with the Kotlin RouterFunction Dsl because when we declare a route with GET("/foo") { ok() }, we can't use the RequestPredicates.Visitor.
The only missing information for generating a kind of automatic documentation is the return type, we need to create a custom RequestPredicate only used to specify the return type of the route.
@tgirard12 Could you please detail the limitations with Kotlin RouterFunction Dsl? I don't see what would prevent the Kotlin version to work while this Java version is working.
It will work fine with the Kotlin DSL and a RouterFunctionDsl. The only limitation is when your want to use the RequestPredicates.Visitor for only one route in a Router. But I think it will not be the common use case.
https://github.com/springdoc/springdoc-openapi README mentions "spring-webflux with Functional Endpoints, will be available in the future release". Maybe worth contacting them for functional WebMvc and WebFlux support?
We have been collaborating with @poutsma and the project lead of Springdoc to implement functional support of OpenAPI, and it is done, see https://github.com/springdoc/springdoc-openapi/issues/891. Let's try to integrate that in Spring Fu for 0.5.0.