Generating Swagger as part of a Maven Build

Most of my projects use Maven to build and coordinate dependencies and run unit and build integration tests. I’ve found it a real pain that I could not generate my swagger docs as part of the build.

I have found a really easy way. In Jenkins, I have a downstream job that runs specific maven goals. The WebSphere Liberty maven goals are documented WebSphere Liberty Maven Documentation. Please note my downstream job is an experimental downstream project; I am a bit concerned about edge cases where the process dies.

The commands of the downstream job are:

mvn dependency:copy-dependencies liberty:install-apps liberty:test-start-server

The commands execute three key elements:

  1. Dummy Server.xml – attached at the bottom
  2. Execution for Goal for pre-integration-test
  3. Execution must follow the copy-dependencies so the war file is copied on in

You can check your server is up and running:

tail -f target/liberty/wlp/usr/servers/defaultServer/logs/messages.log

Download the Swagger (YAML)

curl http://localhost:9080/swagger/api/swagger.yaml -o myswagger.yaml

The full code is below

Swagger Enumerations in YAML

Recently, I have been spending time looking at the Swagger 2.0 Specification.  There XML representation and Enumerations are tricky.  Here is an example of a Swagger Enumeration in YAML.

You can test the YAML https://gist.githubusercontent.com/prb112/59b9cb4ad3d2df19911c/raw/7db2a16b353d8dde5bb3743001f46f7b67b6c431/enumeration.yaml at http://petstore.swagger.io/#!/default/get_demo

 

Swagger with Enumeration
Swagger with Enumeration