Automated HTTP API documentation

[sdeleuze]

OpenAPI: we should try springfox/springfox#1773 which has been merged and see if functional support is ok.

Spring REST docs: we should test WebTestClient support, see spring-projects/spring-restdocs#384.

[wilkinsona]

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.

[sdeleuze]

Indeed, but we can maybe leverage RouterFunctions.Visitor like we do for logging is order to build such OpenAPI spec. Any thoughts @poutsma?

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

[tgirard12]

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.

[tgirard12]

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 :
spring-projects/spring-framework@master...tgirard12:webflux-visitor

[sdeleuze]

I will work on that before Spring Boot 2.1 GA.

[sdeleuze]

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 spring-projects/spring-restdocs#213.

[sdeleuze]

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

[tgirard12]

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.

[sdeleuze]

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

[tgirard12]

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.

[sdeleuze]

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?

[sdeleuze]

We have been collaborating with @poutsma and the project lead of Springdoc to implement functional support of OpenAPI, and it is done, see springdoc/springdoc-openapi#891. Let's try to integrate that in Spring Fu for 0.5.0.