We use Confluence for our company’s documentation, and as such we need to keep samples and documentation up-to-date, but ideally without any work on our part, so we automated it. The goals are:

• Have complete and up-to-date documentation of our APIs and up-to-date code samples in Confluence
• Notify stakeholders (other teams) of any breaking changes before they go into production and give them a few days to prepare or let us know so we can delay the release

We document our APIs using Swagger, which gets us a good part of the way there. We accomplished the second goal by doing the first one twice (instructions below): deployments to our Staging server publish documentation to one confluence section, which stakeholders can subscribe to and get a diff whenever we update the page (again we don’t have to do this), and then our Production deployment publishes documentation to the production section on confluence. We also use semantic versioning for our APIs, which give our stakeholders a really quick idea of what we intend with the release.

Steps:

• Set up swagger for your project. There’s a really good guide here: https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1
• During release, after the site has been deployed, download the latest swagger.json
• Use swagger-confluence-cli to post it to Confluence

Install the Generate Release Notes Build Task from the Azure DevOps Marketplace

https://marketplace.visualstudio.com/items?itemName=automagically.DownloadFile

In the release, add an Agent phase (if you don’t already have one)

Add the DownloadFile Task and a PowerShell Task after the tasks which deploy your project (your site needs to be reachable at this step)

Download swagger-confluence-cli and save it to a local folder on your build servers*. https://cloud.slkdev.net/swagger-confluence/cli/

• Alternatively, you can package it into nuget package and reference it in your project; or place it in your repo; load it as a separate artifact from another repo; or have it accessible on a network drive. I found that if we place it on the build servers, we don’t need to download artifacts in the Agent Phase, which makes our release a bit faster.

Configure the Download File task to point to your just releases project’s swagger.json

Next, configure the powershell script to convert the swagger json into html pages and post them to your confluence site

java -jar "c:\agent\tools\swagger-confluence-cli-all-2.2-RELEASE.jar" -u "https://confluence.mysite.com/rest/api/" -b "$(ConfluenceCredentials)" -a $(ConfluenceParentPage) -g "false" -i "false" -k "$(ConfluenceSpace)" -s "$(System.DefaultWorkingDirectory)\swagger.json" -t "$(ConfluencePageName)" -m "single"

Next, we need to add all the Variables we referenced:

ConfluenceCredentials is your base64 encoded username:password