Including Swagger Docs into your DevOps Pipeline

On my last two posts I went through setting up CI for your PHP project. While I promised this post would cover setting up CD for your pipeline, I realized that I left out a fairly useful (but in my mind unique) part of the process. Our PHP application is using Laravel as the back end, and we are utilizing the inherent capabilities to setup PHP APIs to pass information back and forth from our UI to the back-end. We wanted these APIs documented to assist with both understanding what was available to use, and also to assist with testing, and decided to go with Swagger.

The big issue we ran into was that Swagger lacked the capability to quickly and easily display Swagger documents to the whole team. So I decided to build a process to fix this into our DevOps pipeline.

The Setup

One of the main reasons we went with Swagger is because of it’s lightweight, relatively easy to write-up, and provides not just documentation, but also the ability to run queries from the documentation itself. We created a YAML file for our swagger doc, and put this document in our git repo. This way, each time new APIs were added, or changes were made to our APIs, we would also update this YAML file, which would keep everything in-sync. Previously, we were having to paste this YAML file into the swagger io editor, but this presents a few issues, the worst being potentially exposing your code to the outside world. I decided to figure out how to install the Swagger viewer into our SecureCI^TM machine.

After scouring the web for a bit, I eventually found a nice github repo with a bunch of swagger tools. I decided to install the swagger-ui (viewer) from that repo, leaving the swagger-editor out, as something that users should be able to do locally. The instructions on the README.md file work quite well. So, I downloaded the files in the dist folder, and installed those into /var/lib/swagger/ on SecureCI^TM.

This meant also updating the Apache setup on SecureCI^TM to give access to the swagger docs viewer. I edited /etc/apache2/sites-enabled/ssl and added the below Alias:

Alias /swagger "/var/lib/swagger/"
<Directory "/var/lib/swagger/">
Require all granted
</Directory>

After restarting Apache, I was able to go to [secureci-url]/swagger/ and view the default API docs that came with swagger.

Integration

The last step in this process was to hook these documents into our DevOps pipeline. When pushing the application package into Jenkins for future deploys, I added a section to that job to copy the YAML file into our swagger installation folder. This way, each time we are satisfied with our application, after our DevInt tests, the new documentation is pushed into SecureCI^TM so that the entire team has access.

cp [yaml-file].yaml /var/lib/swagger/

Finally, I needed to update the index.html file included with the swagger-ui to point to this new file. I changed line 39 to read as follows:

url = "https://[secureci-url]/swagger/[yaml-file].yaml";

And that is it. Now upon going to the swagger-ui, any team member can view this documentation.

Stay tuned for the final post next month on finishing our DevOps pipeline for our PHP project.