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

My Experience with maven-antrun-plugin

I’ve been spending some time with maven so that files which matched a certain criteria were automatically moved in the project – OpenNTF SocialSDK.  The files only should be moved when the files don’t have -SNAPSHOT at the end of the version.

I started modifying some code that used maven-antrun-plugin, which bridges the maven-ant worlds.  I tried mixing complex conditional depends on and unless statements from Ant targets and Ant Tasks. Where the target “depends” on another target, you should be able to conditionally execute a target.  I wrote the code, however it never ran cleanly, always throwing an error.

I split the ant tasks and targets into a separate file, and the code now runs cleanly.  From the best practices I’ve read it’s better to pick one, and only use one Maven file or Ant file, I however couldn’t get it to read depends on targets.

I hope you find this ant-maven hack as helpful as I did.

 

The solution is found in the commit – added support for automatically moving the cdnjs files when a release.