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:
- https://app.swaggerhub.com/apis/accountName/apiName/version
- https://api.swaggerhub.com/apis/{owner}/{api}/{version}
Private repositories require API Key.
