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:
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.
Install the Generate Release Notes Build Task from the Azure DevOps Marketplace
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/
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