Using Github, Azure Devops, Gitlab, Bitbucket, SwaggerHub with “Visualize OpenAPI (Swagger) documentation” App

It is easy to include OpenAPI specification stored in GIT repository to your Confluence page. “Visualize OpenAPI (Swagger) documentation” app supports multiple public GIT repository providers such as Github, Microsoft Azure DevOps, Gitlab, Bitbucket and others.

Just copy and paste the URL from browser’s address bar to the widget configuration. Works for most repositories. Public and private access are supported.

No need to type in complicated API requests manually. Application will automatically generate the service specific request and retrieve data for you.

OpenAPI’s $ref reference is supported for external files in public and private repositories.

IMPORTANT: Security risks associated with the feature when using private repositories!

Because of the implementation of application integration in Confluence, all application parameters (including username, password, access token) are exposed into the source code of the page. They’re also accessible in the browser’s development console as part of the HTTPS request to remote repository server.

This means everybody with read access to the Confluence page with a widget configured to access private repositories can view credentials to private repository.

This is not a bug or security breach. It is a know conceptual limitation, there is no way to implement it differently. Credentials are not exposed to people without read access to the Confluence page with an app.

In order to minimise risks when using private repository:

  • Assign the minimum required (read only) permissions when generating a token or service user account for remote repository.
  • Carefully grant the access to the pages that contain widget using remote repository.
  • Do not configure application to use private remote repositories on the public pages.
  • For a sensitive remote repositories copy and paste the source of the specification to the widget on the Confluence page, do not specify username/password or access token in the widget.

See usage instructions below.

Github

URLs can be copied from browsers address bar.

Supported URL formats examples:

  • https://github.com/stripe/openapi/blob/master/openapi/spec3.json
  • https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
  • https://api.github.com/repos/stripe/openapi/contents/openapi/spec3.json?ref=master

Private repositories require personal access token.

Microsoft Azure DevOps

URLs can be copied from browsers address bar.

Supported URL format examples:

  • https://dev.azure.com/microsoft/windows/_git/windows10?path=general%2Fcommand.yaml
  • https://dev.azure.com/microsoft/windows/_git/windows10/commit/4e3aa3b39a2a6488b3e0ac1d7d6aaf22cdeb0d5e?refName=refs%2Fheads%2Fmain&path=general%2Fcommand.yaml&_a=compare

Private repositories require personal access token.

Gitlab

URL need to be manually typed in.

Supported URL format:

  • https://gitlab.com/api/v4/projects/22287398/repository/files/spec3.json/raw?ref=master

Private repositories require personal access token.

Bitbucket

URLs can be copied from browsers address bar.

Supported URL format examples:

  • https://bitbucket.org/organiaztion/project/src/branch-name/src/path/to/the/file
  • https://bitbucket.org/organiaztion-name/project-name/src/commit-hash/src/path/to/the/file?at=main

Private repositories require account username and private password.

SwaggerHub

URLs can be copied from browsers address bar or obtained from ‘Share and Collaborate’ menu.

Supported URL format examples:

Private repositories require API Key.

--

--

--

Engineering Manager / Agile Coach

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

The Best Platforms for Learning Java From Scratch

Serverless: Just Ship the Code

WHAT ARE COMMON KID’S CODING LANGUAGES?

An “AI generated” blog post from Jasper on ’10 Tools to Help You Write Better Code’

python

Google Sheets Contact Form

The FilmOps Precedent

How ZingChart Can Help Web Dev Teams in the Finance Industry

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Andrey Stepanov

Andrey Stepanov

Engineering Manager / Agile Coach

More from Medium

Automating Planetscale Deploy Requests into our CI/CD

Introduction to Github Actions

[How to ] Change your Admin Passwords in Open Distro for Elasticsearch on Centos 7.x

What is Microservice & Monolithic Architectures?