3rd Party Integrations

After generating your OpenAPI definitions (either locally or in CI) you can transfer this document to a variety of 3rd party services to create documentation, commit to your repo for later review, or distribute to your end users.

• Postman
• GitHub Actions
• Atlassian Compass
• Readme.com

Postman

After generating your OpenAPI definitions you can import to Postman as a new collection or update an existing collection.

To add your OpenAPI definition to Postman start by selecting the Import button found in the top right corner of the Postman UI.

Next, select the path to where you saved your OpenAPI definition. Alternatively if you have committed the file to a repository or pushed to a 3rd party API hosting service you can select a code repository or link as the location.

After Postman validates your OpenAPI definition, you can adjust any advanced settings or accept the default import settings.

After the import completes you’ll see a full tree view of your OpenAPI definitions that were generated by AppMap. You can now use Postman to interact with the APIs.

Refer to the Postman documentation for additional details on using Postman to interact with your APIs.

GitHub Actions

If you create OpenAPI definitions in GitHub, the add-commit GitHub action can be used to commit this file to your project on each build.

Example:

- name: AppMap Generate OpenAPI Definition
  run: npx @appland/appmap@latest openapi --output-file openapi.yml
- name: Commit OpenAPI Changes
  uses: EndBug/add-and-commit@v9
  with:
    default_author: github_actions
    add: 'openapi.yml'

Refer to the add-commit documentation for more configuration examples.

Atlassian Compass

Atlassian Compass is a developer experience platform that brings your distributed software architecture and the teams collaborating on them together in a single, unified place. Compass supports visualizing your OpenAPI docs using SwaggerUI integrated into the main Compass application. After adding your application as a new component in Compass, and after enabling the SwaggerUI app, you can now add an additional task to push the openapi.yml file to Compass via a webhook.

After generating an API username and token, create a step in your GitHub Action (or other CI tool) to push the file to Compass using the custom URL in the configuration page. Make sure to store the webhook URL, API user, and API key as encrypted secrets in your build task.

  - name: AppMap Generate OpenAPI Definitions
    run: npx @appland/appmap@latest openapi --output-file openapi.yml
  - name: Push OpenAPI to Atlassian Compass
    run: curl -X PUT ${COMPASS_WEBHOOK_URL} -F file=@openapi.yml --user "$COMPASS_API_USER}:${COMPASS_API_KEY}"

Refer to the Compass documentation for additional information on how to upload your definitions

Readme.com

Readme is a powerful developer hub that can consume your OpenAPI definition and provide a simple way for users to interact with your API directly from your documentation site or with the included client SDKs that Readme provides.

Simply access your Readme administration page, and go to API Settings to add a new endpoint.

Add the relevant commands to your GitHub Action or your CI system. Make sure to save the Readme API key as an encrypted secret in your build task.

- name: Install rdme
  run: npm install rdme@latest -g
- name: AppMap Generate OpenAPI Definitions
  run: npx @appland/appmap@latest openapi --output-file openapi.yml
- name: Push OpenAPI to Readme
  run: rdme openapi openapi.yml --version=v1.0 --key="$"

After your build job completes you’ll see your API imported into Readme.

And when navigating into any of your API endpoints, you’ll see notifications that this API is synced from Swagger.