C# / .NETSecurityDevOps
C# / .NET
Publishing Swagger API Documentation to Confluence during Release
Alexandru Puiu
Alexandru Puiu
September 21, 2018
1 min

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.

swagger demo

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)

swagger tasks

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

swagger download file

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

swagger powershell
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:

swagger variables

ConfluenceCredentials is your base64 encoded username:password


Tags

utils
Alexandru Puiu

Alexandru Puiu

Engineer / Security Architect

Systems Engineering advocate, Software Engineer, Security Architect / Researcher, SQL/NoSQL DBA, and Certified Scrum Master with a passion for Distributed Systems, AI and IoT..

Expertise

.NET
RavenDB
Kubernetes

Social Media

githubtwitterwebsite

Related Posts

Uploading Large Files
Upload Large Files in C#
September 21, 2020
4 min
© 2022, All Rights Reserved.

Quick Links

Get In TouchAbout Me

Social Media