Provide a WebMvc.fn / WebFlux.fn functional DSL

Hey,

Thanks for creating this project. As a follow-up of #546 created by @nlochschmidt, where you added support for Spring web functional DSLs with a mix of Visitor patterns and annotations like @RouterOperations and @RouterOperation, I am wondering if you would be interested to explore the possibility to provide an alternative functional API to these annotations that could be used with the router DSL.

I am not an OpenAPI guru, but I tend to think that programmatic APIs and method references could allow springdoc-openapi to provide an API more consistent with WebMvc.fn / WebFlux.fn mindset, with more compile-time checks and avoiding mixing too much annotation and functional paradigms. That would also allow functional Spring applications like the one incubated in https://github.com/spring-projects-experimental/spring-fu that I created to use springdoc-openapi.

I am not sure yet what it would look like, but if you are interested to move forward this idea, I will be happy to provide some insights on the Spring Framework side of things, on Kotlin related DSLs, or even discuss potential missing extension points. It could also be potentially interesting to compare external versus “in the router” OpenAPI meta information definition.

Any thoughts?

[bnasslahsen]

@poutsma, @sdeleuze,

I confirm the integration is successful, with the last spring master version. This the link for some samples, how the integration will look like:

• HelloRouter
• QuotesRouter
• BookRouter
• EmployeeRouter
• PositionRouter

I will still have to make some final changes, but the most important ones are already done.

[bnasslahsen]

Hi @sdeleuze (Ou bien plutôt bonsoir Sébastien!),

The @RouterOperation annotations are the simplest workaround that we find out, to answer the rising demand to support the functional approach:

• This annotations allow developers to add some OpenAPI metadata to describe their REST endpoints.

Ideally, the springdoc-openapi should be only the bridge between spring-projects and OpenAPI 3 projects: Without even adding extra annotations for the developer:

• This is quite simple in spring-mvc/webflux projects that relies on the annotations (@RestController, …). We have all the information available to generate the documentation even the developer doesn’t add any OpenAPI annotation.
• But as you know, it’s much more difficult with the functional approach as the routes don’t contain by definition all the metadata about their inputs/outputs: Lambdas are passed as arguments which makes introspection difficult to get their concrete inputs/outputs parameters.

I would say that providing an end to end functional API, will be more interesting for projects, choosing the functional paradigm because it:

• Will make the life of the developer easier
• Will make the code simpler to maintain and more consistent
• Will make the maintenance of springdoc-openapi project simpler as well!

What we need is an extension to the existing router DSL, that allows developers to add more metadata (that are not available on the router defintion) about their REST endpoints, without any extra annotations.

And Ideally, even the developer doesn’t add this metadata, it should be possible to generate automatically minimal API description as we propose on the projects that are not using the Functional Endpoints. (But i am not sure this point is quite simple to achieve)

It’s a great pleasure to know that you are interested in the project. I am open to discuss more in details this idea. If you need more inputs, i would be more than happy to help.