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.Ĭonfigure the Download File task to point to your just releases project’s swagger.json * 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. In the release, add an Agent phase (if you don’t already have one)Īdd the DownloadFile Task and a PowerShell Task after the tasks which deploy your project (your site needs to be reachable at this step)ĭownload swagger-confluence-cli and save it to a local folder on your build servers*. Install the Generate Release Notes Build Task from the Azure DevOps Marketplace – Use swagger-confluence-cli to post it to Confluence – During release, after the site has been deployed, download the latest swagger.json We also use semantic versioning for our APIs, which give our stakeholders a really quick idea of what we intend with the release. 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 document our APIs using Swagger, which gets us a good part of the way there. – 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 – Have complete and up-to-date documentation of our APIs and up-to-date code samples in Confluence 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.

How to use confluence for documentation