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

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.

Postman Import

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.

Postman Import File

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

Postman 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.

Postman Import Complete

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

Add & Commit: GitHub Actions

After your OpenAPI definition is created by your GitHub Action, you can use the add-commit GitHub action 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.

Compass SwaggerUI Configuration

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.

Readme Synced OpenAPI Definitions

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

Readme sync OpenAPI definition

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.

Readme API Docs imported

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

Readme sync API docs


Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!