Using spring restdocs to generate REST documentation

Flowable Engine
1

What do you think about using spring-restdocs and spring-auto-restdocs that generates asciidoc documentation based on the Javadoc that is in code itself.

I have already create a small WIP PR #619 for one group endpoint.

One good thing about generating the documentation from code is that you can combine it with the tests, i.e. a test with the example data and requests that are used will be used. This also means that we would need to switch to using Spring MockMvc (which by the way makes things simpler and easier for testing)

1 Like
2

Hi Filip,

Thanks for creating the PR as an example. Having better documentation of the REST API that can be generated from the code is always good to have. This could replace the statically written documentation we have in the user guides. I still like Swagger as well, as it gives a different way of REST API description and it’s widely used.

Best regards,

Tijs

3

Hey Tijs,

Replacing the statically written documentation is what I had in mind (with the addition of improving the tests with spring-mvc-test :wink:).

I like Swagger as well, is a different kind of documentation, so I would have both. Maybe it’ll be worth it to see if there is a way for Swagger to pick up the documentation from the Javadoc, so we can have one place for everything.

I am also looking into using POJOs for the Map<String, String> request parameters. If we have that then it would also be easier for Swagger to generate better documentation (as we would use @ApiModel on the POJOs). This is how that can be achieved.

Cheers,
Filip

4

Aloah,

My 2cts about this topic.

In one side we have OpenAPI Specification (Swagger V2 annotation used inside Flowable) & on the other side we have Spring Rest Docs & Auto Rest Docs.
Sadly (or happilly) both “libs” (its not really libs on both side but lets use this term for simplicity) have clearly different purpose and approaches but overlap (in flowable case) in API static doc generation.

OpenAPI is a standard specification to describe a REST API. It’s vendor neutral and backed by the OpenAPI initiative which includes a lot of big company (Google, Microsoft, IBM, Atlassian…). The latest version of the Specification (V3) has been release few months ago.

As industry standard, Flowable MUST provide the spec files for all its public REST API in this format.
I would go a little bit further and even said those files should be considered as release deliverable the same way as the flowable jar libs or war apps.

Now because those files are becoming standard description format for REST API a lot of tools/companies/projects can use this file to do different things like

  • Creating an environment to design and collaborate on API
  • Improving API Discoverability
  • Creating static documentation or website
  • Generating Client/Server implementation
  • Improve API Test Automation
  • Better API Monitoring
  • Easier API Integration
    etc…

It’s the purpose of having standard! It’s a way to make everybody life easier and integrates each other more easily.
And as you can see generation documentation is only one way to use the spec file.

On the other hand we have Spring Rest Docs & Auto Rest Docs which are completely dedicated to generate static documentation (asciidoc or markdown) based on Spring MVC information but also helps testing/documentation works better together by using Spring MVC Test or Rest Assured. Worth to remind this lib target only Spring related Project. It’s a spring tool to make spring developer happier generating their Rest API documentation & validation.

The fact is documentation generated by Spring Rest Docs is better & easier than Swagger V2 annotated spring project. Swagger V2 has indeed some design issues and even if you annotated all Spring RestController it wouldn’t cover all the subtle that Spring MVC / Rest Doc understand by default.

Nevertheless Open API Spec (in its latest version V3) resolved those design issues and is more flexible than Swagger V2.

The question now is what does it means for Flowable ?

First let’s look at the current situation:

  • Flowable Rest API uses Swagger annotation to generate spec file (V2).
  • Sadly due to legacy & API design & choice (made X years ago) the spec file generated doesn’t cover 100% of the usage (one endpoint returns different response, generic parameter/response,…)
  • Userguide documentation is sometimes better to cover those specific use case.
  • Userguide documentation sometimes missed new API documentation or are not aligned with the code (response code, parameter format…)

Now what’s Flowable goal ?

  • Migrating Swagger V2 spec to Open API Spec V3
  • Delivering Open API Spec file as artifacts
  • Generating automatically static Rest API documentation (instead of manual writing)
  • Improve API usability & discoverability

How ?
This is where things get complicated…

Migrating Swagger V2 spec to Open API Spec V3
As the V3 is still recent, dev tooling is still not missing/incomplete (no maven plugin to generate open api spec file).
If done right now it must be manually created or using a translator from V2 to V3.

Delivering Open API Spec file as artifacts
Something not really complicated on V2 with the drawback it’s incomplete.
Needs work for V3

Generating automatically static Rest API documentation (instead of manual writing)
For this case, Spring Rest Doc is a good candidate if flowable doesn’t migrate to V3 in short period or doesn’t consider OpenAPI as the utility to generate static doc.

Improve API usability & discoverability
If Spec file are delivered as artifacts it would be easy for devs/users to use 3rd party Solutions/Apps to create their own integration.

My 2 cts.

NB: Something I forget to mention is also the direction or path to generate the specfile.

There’s 2 approaches (at least…)

  • From specification file to generation
  • From Code to Spec file to generation

In first case we consider the spec file as the single trusted point for API description (same way you can consider an UML diagram for example or in BPM world it’s the modelling phase ^^) So any difference found in the code should be considered as an issue/bug.

In the second case we consider the spec file as the code reflection and status. Which means the right stuff is done by the code and we publish only the spec file as a result.