Use GIT repository to host YAML/JSON definitions: Bitbucket, GitHub, GitLab
- Toshihiro Sato
1. GitHub
a) Public repository
Browse the definition file and click Raw button to get the URL to use in the macro:
You will have the URL of you file with this format: https://raw.githubusercontent.com/{author}/{repository}/{branch}/{file path}
Example: https://raw.githubusercontent.com/swagger-api/swagger-ui/master/petstore.json
b) Private repository
You need to create personal access token and input this access token to the Access token field of the macro dialog:
The URL of your definition must follow this format: https://api.github.com/repos/{author}/{repository}/contents/{file path}
Example: https://api.github.com/repos/swagger-api/swagger-ui/contents/definitions/petstore.json?ref=demo
2. GitLab
You need to get the URL which points to your definition file to input to macro’s URL field.
a) Public repository
Browse the definition file and click Raw button to get the URL to use in the macro:
You will have the URL of you file with this format: https://gitlab.com/{author}/{repository}/-/raw/{branch}/{file path}
Example: https://gitlab.com/linhtechnology/swaggerui/-/raw/master/petstore.json
If you meet CORS issue when using above URL, you need to change to this format: https://gitlab.com/api/v4/projects/{project id}/repository/files/{file path}/raw?ref={branch}
Example: https://gitlab.com/api/v4/projects/18849679/repository/files/petstore.json/raw?ref=master
b) Private repository
You need to create personal access token and choose api scope for this access token. Copy the personal access token to use in this URL format: https://gitlab.com/api/v4/projects/{project id}/repository/files/{file path}/raw?ref={branch}&private_token={personal access token}
You can see your project ID under your project name:
3. BitBucket
If you use bitbucket.org, you need to use this format:
https://api.bitbucket.org/2.0/repositories/{yourcompany or account}/{repository}/src/master/{filepath}
Example:
https://api.bitbucket.org/2.0/repositories/toshihirocompany/openapi/src/master/yaml/swagger.yaml
a) Public repository: You only need to input your file URL with above format to URL field
b) Private repository: You need to input your file URL, username and password to access your file. You can create an app password to use: https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/