Publishing Documentation to Confluence

Want to get your documentation published to Confluence quickly and smoothly? Follow these steps!

Step 1: Add the Documentation Template 📖

Start by creating a docs folder in your repo. Inside this folder, copy these files:

• nsdocs.yml — configures where in Confluence your docs will be published
• _attributes.adoc — for setting key attributes which are used in the template
• apihomepage.adoc — your API content

Make sure to replace all the TODO comments in these files with your API specific information.

nsdocs.yml

# pick the page ID of the parent page you want to publish *under* from the page URL. This page will not be modified.
# Find it in Confluence by navigating to the page and looking at the URL in your browser.
default-parent-id: 153026795 # The default parent ID under which we document NSAPP apis

# your own space (e.g. ~john.doe), or a team space (e.g. MLAB)
space: MLAB

# pick any string that makes your project unique; e.g. a git URL
tenant: #TODO: add unique string

_attributes.adoc

:SONARQUBE_ID: //TODO: Add SonarQube ID, for example NSAPP_bookstore-demo-api
:SONARQUBE_TOKEN: ${SONARQUBE_TOKEN} # Injected by the build pipeline
:SONARQUBE_URL: https://sonarqube.topaas.ns.nl
:API_NAME: //TODO: Add API name in Azure API Management, for example bookstore-demo-api
:API_FRIENDLY_NAME: //TODO: Add human readable API name, for example Bookstore Demo API
:SLACK_CHANNEL: //TODO: Add your teams slack channel, for example backpack
:REPOSITORY_URL: //TODO: Add your repository URL, for example https://dev.azure.com/ns-topaas/NSAPP/_git/backpack

apihomepage.adoc

= {API_FRIENDLY_NAME}
include::_attributes.adoc[]

toc::[exclude="DO NOT EDIT"]

== Overview and Current Status

ifdef::SONARQUBE_TOKEN[]
=== SonarQube Status

[cols="1a,1a,1a,1a,1a,1a"]
|===
| image::{SONARQUBE_URL}/api/project_badges/measure?project={SONARQUBE_ID}&metric=alert_status&token={SONARQUBE_TOKEN}[Quality Gate Status,height=20]
| image::{SONARQUBE_URL}/api/project_badges/measure?project={SONARQUBE_ID}&metric=coverage&token={SONARQUBE_TOKEN}[Coverage,height=20]
| image::{SONARQUBE_URL}/api/project_badges/measure?project={SONARQUBE_ID}&metric=sqale_index&token={SONARQUBE_TOKEN}[Technical Debt,height=20]
| image::{SONARQUBE_URL}/api/project_badges/measure?project={SONARQUBE_ID}&metric=security_rating&token={SONARQUBE_TOKEN}[Security Rating,height=20]
| image::{SONARQUBE_URL}/api/project_badges/measure?project={SONARQUBE_ID}&metric=reliability_rating&token={SONARQUBE_TOKEN}[Reliability Rating,height=20]
| image::{SONARQUBE_URL}/api/project_badges/measure?project={SONARQUBE_ID}&metric=sqale_rating&token={SONARQUBE_TOKEN}[Maintainability Rating,,height=20]
|===
endif::[]

=== Environments

[%header, cols="1a,1a,1a"]
|===
| Environment
| API Portal
| Endpoint
| Test
| https://apiportaltst.ns.nl/api-details#api={API_NAME}
| https://gateway.apiportaltst.ns.nl/{API_NAME}
| Acceptance
| https://apiportalacc.ns.nl/api-details#api={API_NAME}
| https://gateway.apiportalacc.ns.nl/{API_NAME}
| Production
| https://apiportal.ns.nl/api-details#api={API_NAME}
| https://gateway.apiportal.ns.nl/{API_NAME}
|===

=== Useful links

[cols="1a,1a"]
|===
| Jira
| // TODO: Link to your JIRA board [Jira Page,window=_blank]
| Team page
| //TODO: Link to your Team page[Team Page,window=_blank]
| Slack
| slack:channel[{SLACK_CHANNEL}]
| SonarQube
| https://sonarqube.topaas.ns.nl/dashboard?id={SONARQUBE_ID}[SonarQube,window=_blank]
| Repository
| {REPOSITORY_URL}
| README
| {REPOSITORY_URL}?path=/README.md
|===

== Features

=== Bookstore Demo API

//TODO: Add a description of the functionality of your API here.

== Architecture

//TODO: Include a diagram or description of the architecture of your API here.

Step 2: Publishing the docs from your Pipeline ⚙️

To publish the docs automatically from your CI/CD pipeline, follow these steps:

Adding secrets

By default, we use a library called NSDocs to manage the required secrets. Add the following:

TIP

The ConfluenceUserName and ConfluenceApiKey secrets are already created in the NSDocs library in the NSAPP Azure DevOps environment. You only need to add the SonarQube token there.

Secret	Key	Value
SonarQube token	SonarQubeToken-<your-api-name>	Retrieve via: https://sonarqube.topaas.ns.nl/api/project_badges/token?project=<YOUR_PROJECT_ID> Example: https://sonarqube.topaas.ns.nl/api/project_badges/token?project=NSAPP_homepage-bff
Confluence username	ConfluenceUsername	NS e-mail address without the @ns.nl part. Preferably use a functional account.
Confluence API key	ConfluenceApiKey	Generate here: Atlassian documentation

Integrate into your pipeline

• Reference the NSDocs library in your main pipeline file like this:

  variables:
    - group: NSDocs

• Add the docs.yml file into your pipeline folder.
  docs.yml

  parameters:
    - name: confluenceUsername
      type: string
    - name: confluenceApiKey
      type: string
    - name: nsdocsVersion
      type: string
      default: latest
    - name: docDir
      type: string
      default: ./docs
    - name: registryServiceConnection
      type: string
      default: NSPAAS-HARBOR-PUSH-PULL-$(System.TeamProject)
    - name: sonarqubeToken
      type: string
      default: ''
  
  jobs:
    - job: DeployDocs
      displayName: "Deploy docs"
      steps:
        - task: Docker@2
          displayName: "Login to Harbor"
          inputs:
            command: login
            containerRegistry: ${{ parameters.registryServiceConnection }}
        - script: |
            echo "Replacing \${SONARQUBE_TOKEN} with pipeline secret"
            sed -i "s|\${SONARQUBE_TOKEN}|$SONARQUBE_TOKEN|g" ${{ parameters.docDir }}/_attributes.adoc
          displayName: "Inject SonarQube token"
          env:
            SONARQUBE_TOKEN: ${{ parameters.sonarqubeToken }}
        - script: |
            docker run --rm -i -e "CONFLUENCE_USERPASS=${{ parameters.confluenceUsername }}@ns.nl:${{ parameters.ConfluenceApiKey }}" \
              -e "WORKDIR=${{ parameters.docDir }}" \
              -v "$(Build.SourcesDirectory):/project" \
              container-registry.nspaas.ns.nl/qes-public/docs-as-code:${{ parameters.nsdocsVersion }} publish
          displayName: "nsdocs publish"

• Integrate the PublishDocs template inside your main pipeline file like this:

      - stage: PublishDocs
        displayName: "Publish docs"
        dependsOn: [ ]
        condition: |
          eq(variables.isMain, true)
        jobs:
          - template: ./ci/docs.yml
            parameters:
              confluenceUsername: $(ConfluenceUsername) # Retrieved from the NSDocs secret
              confluenceApiKey: $(ConfluenceApiKey) # Retrieved from the NSDocs secret
              nsdocsVersion: 0.1.9
              sonarqubeToken: $(SonarQubeToken-bookstore-demo-api) #TODO: Reference your own token from the NSDocs secret here. 
              docDir: apps/bookstore-rest-api/docs #TODO: Reference your own docs directory here.

With this, every pipeline run can automatically publish your updated docs to Confluence.

Examples 🔍

Want inspiration or a quick start? Check out these examples:

• Example Pull Request
• Example published Confluence page
• Homepage BFF repository
• Bookstore REST API repository

These will give you a clear idea of the setup and outcome.

More information 📚

This how-to guide is using NSDocs to publish Asciidoc documentation to Confluence. For more details, check out the NSDocs documentation