coldbrewcoderss/swagger-diff repository overview

swagger-diff is a small web-service written in C# ASP.NET that exposes a webhook in order to detect Swagger API documentation changes and respond with alert messages on your slack workspace.

First, you will need to create a personal slack app and create a slack webhook that will allow you to post messages to a channel in your workspace via a HTTP POST request. You can create an app for your slack workspace here: https://api.slack.com/apps⁠.

Next, create a .env file that defines the following ENV variables. These will govern the configuration and behavior for your instance of swagger-diff:

SWAGGER_DIFF_HOSTNAME={HOSTED_SWAGGER_DOCUMENTATION_ORIGIN/HOSTNAME}
SWAGGER_DIFF_PORT={SWAGGER_DOCUMENTATION_PORT} (default 80)
SWAGGER_DIFF_SERVICENAMES={COMMA_DELIMITED_LIST_OF_WEB_SERVICE_NAMES}
SWAGGER_DIFF_API_VERSION={API_VERSION_NUMBER}
SWAGGER_DIFF_SLACK_WEBHOOK={SLACK_APP_WEBHOOK}

Ex.
SWAGGER_DIFF_HOSTNAME=https://my-swagger-url.com⁠
SWAGGER_DIFF_PORT=443
SWAGGER_DIFF_SERVICENAMES=service1,service2 (<--- NO SPACES!)
SWAGGER_DIFF_API_VERSION=1
SWAGGER_DIFF_SLACK_WEBHOOK=https://hooks.slack.com/services/asdasdfasdf/asdfasdfasdf/asdfasdfasdfasdf⁠

Next run the image with these ENV variables:

docker run --env-file .env -p 8000:80 coldbrewcoderss/swagger-diff:latest

Now you will have a running instance of the container. With the above test config, here is the behavior:

First, the initialization phase of the app runs. This will load Swagger API documentation JSON files from the following two urls:

1. https://my-swagger-url.com:443/api/service1/swagger/1/swagger.json⁠
2. https://my-swagger-url.com:443/api/service2/swagger/1/swagger.json⁠

These documentation JSON files are saved in memory. Next the following 2 webhooks are exposed:

1. GET or POST localhost:8000/api/swaggerdiff/service1
2. GET or POST localhost:8000/api/swaggerdiff/service2

If we send the API request GET localhost:8000/api/swaggerdiff/service2:

• swagger-diff will fetch the Swagger API documentation JSON file from the url: https://my-swagger-url.com:443/api/service2/swagger/1/swagger.json⁠
• swagger-diff will compare the newly fetched file with the previously stored file and check for endpoint additions and removals.
• If API endpoint additions or removals are detected, a slack message will be sent via your slack app and posted in your configured workspace.
• If changes are detected, swagger-diff will save the latest version of the Swagger API documentation JSON file for the web-service "service2" for future comparisons.

The webhooks exposed by swagger-diff are intended to be used by your CICD pipeline. Triggering a request to the exposed webhook after each web-service deployment will alert your development team of API changes automatically, simplifying and automating team-wide communication.