Flowable REST API now includes Swagger docs

More and more libraries and frameworks are adding Swagger support nowadays. For those who don’t know Swagger: it is a standard specification that is part of the OpenAPI initiative. The core of Swagger is a so-called specfile which is a json (or yaml) document that describes and documents for example a REST API. By using Swagger annotations on the Spring MVC REST controllers, the docs and logic stay close together so it’s easy to maintain. A Maven plugin then processes these annotations and generates this specfile.

 

The benefits of Swagger are quite clear:

  • Documentation, obviously
  • Auto-generation of client SDK’s. For example, suppose you are using PHP (or any other language/environment) and want to work with the Flowable API’s, then you can generate a client library using the specfile.
  • API discovery or inclusion in an API directory

Of course, such a json specfile is kind of boring to read, so the Swagger UI has been added to the Flowable REST application. This is an html/javascript application that parses and displays the REST API docs in a user-friendly way. The Swagger UI will be accessible under /docs when running the Flowable REST application. You can also the same UI to actually interact with the API (which imho sure is easier than having to look up how curl works for the xth time ;-))

5 Comments

  1. Yannick Spillemaeckers October 26, 2016

    Looks nice!! I’ve been looking forward to a feature like this.

    I did a few tests and have some feedback. It’s not possible to upload files, so i would be nice for API’s like “POST /repository/deployments” and “POST /runtime/tasks/{taskId}/attachments” to be able to do that. Also, the response body from the rest api always seems to be empty. The service returns a 200 but the data in the response body stays empty.
    Great work !

  2. Alireza Mohammadi October 31, 2016

    I’ve been trying to contact you through twitter and LinkedIn but no luck. Kindly please let me know how I can reach you…

  3. Joram Barrez November 2, 2016

    @Alireza: sorry about that! Checked my twitter/linkedin feed, but can’t seen anything. What’s your twitter handle?

  4. Alireza Mohammadi November 2, 2016

    @Joram, well the point is that I can’t send you a private message on twitter or LinkedIn as you are not following me. My twitter is: @armohammadi

  5. Greg Harley February 8, 2017

    Really great work guys. Keep it up.

Leave a Reply

Your email address will not be published.