@appland/appmap 3.133.0 → 3.134.0

package/built/docs/guides/runtime-code-review.md

@@ -0,0 +1,108 @@
+---
+layout: docs
+title: Docs - Guides
+guides: true
+name: Understanding the Runtime Code Review Report
+step: 8
+---
+
+# Understanding the Runtime Code Review Report <!-- omit in toc -->
+
+AppMap Analysis works with your Continuous Integration (CI) system to collect, store, analyze, and report on the behavioral changes within each Pull Request. AppMap analyzes the changes in your application on each pushed commit or pull request. AppMap performs a thorough analysis of the runtime differences, giving you:
+
+- Root cause analysis of failed tests.
+- Web service API changes - breaking and non-breaking - via comparison of generated OpenAPI definitions.
+- New and resolved security vulnerabilities.
+- New and resolved performance issues.
+- New and resolved flaws in other categories - maintainability, reliability, and user-defined rules.
+- Code Behavior diffs represented as sequence diagrams showing changed runtime behavior within the PR.
+
+<img class="video-screenshot" src="/assets/img/docs/guides/runtime-code-review.webp"/> 
+
+- [The AppMap Change Report](#the-appmap-change-report)
+- [Summary and Status](#summary-and-status)
+  - [Failed Tests](#failed-tests)
+  - [API Changes](#api-changes)
+  - [Security Flaws](#security-flaws)
+  - [Performance Problems](#performance-problems)
+  - [Code Anti-Patterns](#code-anti-patterns)
+  - [New AppMaps](#new-appmaps)
+
+## The AppMap Change Report
+
+Once a Pull Request is opened, reopened, or changed, an AppMap Analysis command will run to build a comparison report between the head revision and the most recent base revision for which an AppMap archive is available.  This ensures AppMap is only analyzing the code which changed in the pull request. This report compares structural differences observed at runtime between the feature and the origin point of that feature branch. The same action can also add comments and annotations to the source code changes involved in the Pull Request. The report data is also available as a JSON file.
+
+Key insights include:
+
+- How the new code will impact the system.
+- Any major architectural changes introduced.
+- Changes to the code interactions from API to Database
+
+Here is an example of a report from AppMap in CI:
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-github-action.webp"/>
+
+This report shows the runtime analysis done by AppMap, which records code execution behavior *before* those changes are approved for deployment to production.
+
+<img class="video-screenshot" src="/assets/img/docs/appmap_CI_report_top.webp"/> 
+
+## Summary and Status
+
+The summary gives you an overview of the following code-related flaws, problems, and anti-patterns. 
+
+- [Failed Tests](#failed-tests)
+- [API Changes](#api-changes)
+- [Security Flaws](#security-flaws)
+- [Performance Problems](#performance-problems)
+- [Code Anti-Patterns](#code-anti-patterns)
+- [New AppMaps](#new-appmaps)
+
+
+### Failed Tests
+
+AppMap will report on any tests that failed as part of your test suite. For each test that failed to complete successfully, AppMap will analyze the failed test, showing the full details of the error and the specific part of the test that failed. 
+
+<img class="video-screenshot" src="/assets/img/docs/appmap_CI_report_failed_tests.webp"/> 
+
+### API Changes
+
+AppMap will report on any changes seen with your API routes at runtime. AppMap will identify changes to routes themselves, notifying you when a new route appears or an existing route is deleted. Additionally, it will identify changes to the response body, content, descriptions, and other attributes.
+
+<img class="video-screenshot" src="/assets/img/docs/appmap_CI_report_api_changes.webp"/> 
+
+### Security Flaws
+
+AppMap analyzes your application's behavior to identify new security flaws in how the new code changes execute.  AppMap can identify issues such as:
+
+- [Deprecated cryptography algorithm](/docs/reference/analysis-rules.html#deprecated-crypto-algorithm)
+- [Logout without Session Reset](/docs/reference/analysis-rules.html#logout-without-session-reset)
+- [Deserialization of untrusted data](/docs/reference/analysis-rules.html#deserialization-of-untrusted-data)
+- and others.
+
+For a full list of all the flaws and issues which AppMap can detect, refer to the [Analysis Rules](/docs/reference/analysis-rules) reference section.
+
+### Performance Problems
+
+AppMap analyzes software behavior changes in your code base to identify performance problems before you merge your code changes. AppMap identifies a variety of software performance problems such as:
+
+- [N Plus One SQL Query](/docs/reference/analysis-rules.html#n-plus-one-query)
+- [Slow Function Calls](/docs/reference/analysis-rules.html#slow-function-call)
+- [Slow HTTP Server Requests](/docs/reference/analysis-rules.html#slow-http-server-request)
+- and others. 
+
+For a full list of all the flaws and issues which AppMap can detect, refer to the [Analysis Rules](/docs/reference/analysis-rules) reference section.
+
+### Code Anti-Patterns
+
+AppMap can identify any major or potential structural flaws in the architecture, or logical flow that could be introduced due to merging the feature into your application. Some examples of these code anti-patterns that AppMap can identify are: 
+
+- [Circular Dependencies](/docs/reference/analysis-rules.html#circular-dependency)
+- [Too Many SQL or RPC Updates](/docs/reference/analysis-rules.html#too-many-updates)
+- [SQL Queries from View Layer](/docs/reference/analysis-rules.html#query-from-view)
+- and others. 
+
+For a full list of all the flaws and issues which AppMap can detect, refer to the [Analysis Rules](/docs/reference/analysis-rules) reference section.
+
+### New AppMaps
+
+New test cases added to a pull request will lead to new AppMaps being created, with one AppMap created for each new test. AppMap will list all of the new AppMaps (and therefore, each new test) created in each pull request. 

package/built/docs/integrations/atlassian-compass.md

@@ -0,0 +1,24 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: Atlassian Compass
+step: 1
+---
+
+# Atlassian Compass
+
+[Atlassian Compass](https://www.atlassian.com/software/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](https://community.atlassian.com/t5/Compass-Alpha-articles/Visualize-your-APIs-in-Compass-with-Swagger-UI/ba-p/1814790) 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. 
+
+<img class="video-screenshot" src="/assets/img/compass-swagger-ui-config.webp"/> 
+
+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.](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
+
+```
+  - 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](https://community.atlassian.com/t5/Compass-Alpha-articles/Visualize-your-APIs-in-Compass-with-Swagger-UI/ba-p/1814790)

package/built/docs/integrations/atlassian-confluence.md

@@ -0,0 +1,50 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: Atlassian Confluence
+step: 1
+---
+
+# Atlassian Confluence
+
+AppMap integrates with [Confluence](https://www.atlassian.com/software/confluence), the popular corporate wiki developed by the Atlassian.
+
+Confluence facilitates robust documentation and knowledge sharing. AppMap automatically generates interactive software diagrams from run-time data, ensuring an accurate and up-to-date understanding of code architecture and behavior. This integration leverages the strengths of both platforms enabling teams to better understand, document, and collaborate on their software projects.
+
+## Requirements
+
+1. A project containing AppMaps.
+  - How to make AppMaps [in your code editor](/docs/setup-appmap-in-your-code-editor/)
+  - How to make AppMaps [using a GitHub action in CI](/docs/setup-appmap-in-ci/) 
+2. [The AppMap app for Confluence](https://marketplace.atlassian.com/apps/1233075/appmap-for-confluence). 
+
+## Add AppMaps to a Document or Blog Post
+
+1. **Enter Edit Mode:** Click the pencil icon to switch to Edit Mode in Confluence.
+  <img class="video-screenshot" src="/assets/img/enter-edit-mode.png"/> 
+
+2. **Attach AppMap File:** Drag and drop the AppMap file from your file system or Finder into the Confluence page.
+  <img class="video-screenshot" src="/assets/img/drag-and-drop-appmap.webp"/> 
+
+3. **Insert AppMap:** Click the plus sign to get the insert menu. Type in and select 'AppMap'.
+  <img class="video-screenshot" src="/assets/img/insert-appmap.webp"/> 
+  A placeholder that looks like this will be added to the page: 
+  <img class="video-screenshot" src="/assets/img/appmap-placeholder-confluence.png"/>
+
+4. **Choose AppMap:** Click the pencil under the placeholder to open the AppMap options.
+  <img class="video-screenshot" src="/assets/img/edit-menu-confluence.png"/>
+   Select the AppMap you want to display from the dropdown menu and it will render.
+  <img class="video-screenshot" src="/assets/img/select-an-appmap-confluence.webp"/>
+    <p class="alert alert-info">  If your AppMap does not render, make sure that you are working on a published document. AppMaps will not render until the document has been published at least once</p>
+
+5. **Adjust Width (Optional)** The width adjustment controls at the bottom of the AppMap window can be used to view more of the AppMap inline.
+  <img class="video-screenshot" src="/assets/img/width-adjustments-confluence.png"/>
+
+6. **Save Changes:** Click the 'Update' button to apply the changes to your Confluence page.
+  <img class="video-screenshot" src="/assets/img/update-button-confluence.png"/>
+
+7. **Fullscreen Mode (Optional):** Click on the 'full screen' icon in the AppMap use Fullscreen mode.
+  <img class="video-screenshot" src="/assets/img/full-screen-control-confluence.png"/>
+    <p class="alert alert-info"> If at any point you would like some help, <strong><a href="/slack">join us in Slack</a>!</strong> You'll find the AppMap team there, along with other AppMap users.</p>
+

package/built/docs/integrations/docker.md

@@ -0,0 +1,108 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: Docker
+step: 7
+---
+
+# Docker
+
+AppMap supports capturing AppMap recordings from inside a Docker container, when using [Docker Compose](https://docs.docker.com/compose/), or when running [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+
+- [Why record AppMaps within Docker?](#why-record-appmaps-within-docker)
+- [Sample Project](#sample-project)
+- [How to run AppMap inside of Docker Engine](#how-to-run-appmap-inside-of-docker-engine)
+- [How to run AppMap inside of Docker Compose](#how-to-run-appmap-inside-of-docker-compose)
+- [Troubleshooting AppMap and Docker](#troubleshooting-appmap-and-docker)
+
+## Why record AppMaps within Docker?
+
+Recording AppMaps inside a Docker container offers several advantages for developers. Docker's containerization ensures a consistent, reproducible environment across various operating systems, which is crucial for diagnosing and resolving issues that may be environment-specific. This uniformity simplifies the setup process, reduces the time spent on environment configuration, and increases the reliability of recorded AppMaps by mirroring the conditions under which software runs in production or other developers' environments. 
+
+Overall, using Docker for recording AppMaps streamlines the development workflow, enhances code quality, and fosters collaboration among team members by ensuring that everyone works within an identical development setup.
+
+## Sample Project
+
+To see an example project using Docker and configured with AppMap, you can see the necessary configuration available on our [sample project on GitHub](https://github.com/land-of-apps/sample_rails_app/).
+
+- [Example Dockerfile](https://github.com/land-of-apps/sample_rails_app/blob/main/Dockerfile)  
+- [Example docker-compose.yml](https://github.com/land-of-apps/sample_rails_app/blob/main/docker-compose.yml)
+
+## How to run AppMap inside of Docker Engine
+
+Using the example [Dockerfile](https://github.com/land-of-apps/sample_rails_app/blob/main/Dockerfile) above you need to make sure that you run Docker with the `-v` or `--volume` options in `docker run`.
+
+For example to run the application with AppMap enabled in the sample project above, you will need to run:
+
+```
+> docker run -p 3000:3000 -v $(pwd)/tmp/appmap:/app/tmp/appmap sample_rails_docker bundle exec rails server -b 0.0.0.0
+```
+{: .example-code}
+
+Let's breakdown what that command is doing:
+
+- `docker run`: Command to create and start a new container.  
+- `-p 3000:3000`: Maps port 3000 on the host to port 3000 in the container.  
+- `-v $(pwd)/tmp/appmap:/app/tmp/appmap`: Mounts the tmp/appmap directory from the current directory on the host to /app/tmp/appmap in the container for file sharing.  
+**NOTE** Update `/app/` in the command to where your application is configured to run.  
+- `sample_rails_docker`: The name of the Docker image to use for the container.  
+- `bundle exec rails server -b 0.0.0.0`: The command executed within the container to start the application.  
+
+After recording your AppMaps, you'll now see them in the VS Code or JetBrains extension.  The maps will also be visible in your local directory in the `tmp/appmap` folder.  
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-appmaps.webp"/> 
+
+## How to run AppMap inside of Docker Compose
+
+Using the example [docker-compose.yml](https://github.com/land-of-apps/sample_rails_app/blob/main/docker-compose.yml) file in our sample project. Here is the relevant part of the config.
+
+```
+services:
+  web:
+    build: .
+    command: bundle exec rails server -b 0.0.0.0
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./tmp/appmap:/app/tmp/appmap
+```
+{: .example-code}
+
+Let's explain the main part of our relevant configuration.
+
+services: Defines the services that make up your application.
+
+- `web`: The name of the first (and in this case, only) service.  
+- `build: .`: Tells Docker to build the Docker image for the web service using the Dockerfile in the current directory.  
+- `command: bundle exec rails server -b 0.0.0.0`: Overrides the default command to start the Rails server, making it accessible from any IP address.  
+- `ports: "3000:3000"`: Maps port 3000 on the host to port 3000 in the container, allowing access to the application via localhost:3000.  
+- `volumes: ./tmp/appmap:/app/tmp/appmap`: Mounts the tmp/appmap directory from the host into the container at /app/tmp/appmap for file sharing.  
+**NOTE** Update `/app/` in the command to where your application is configured to run.  
+
+You can now run `docker compose up web` to launch this container using Docker Compose.  When interacting with the application your maps will be displayed in the VS Code or JetBrains plugin.  The maps will also be visible in your local directory in the `tmp/appmap` folder.  
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-file-share.webp"/> 
+
+
+## Troubleshooting AppMap and Docker
+
+### AppMaps are not visible in plugin with directory correctly mounted
+
+You may experience an issue on Linux where you have correctly bind mounted the `tmp/appmap` directory into your Docker container, but are still unable to see the AppMaps in your project.  
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-no-appmaps.webp"/>
+
+You can confirm this by looking in the `tmp/appmap` directory in your project file directory listing like in the screenshot below:
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-maps-directory.webp"/> 
+
+You can see in that screenshot, a list of AppMap files are visible, and if we opened them in the editor, they would be visible as an AppMap.
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-open-map.webp"/> 
+
+When using Docker on Linux, developers might encounter a situation where directories mounted inside a Docker container as bind mounts (using the -v or --volume flag) are owned by the root user. This happens because, by default, Docker runs its containers as the root user, unless specified otherwise. As a result, any files or directories created inside the container on these bind mounts will also be owned by root.  Because the AppMap files in `tmp/appmap` are now owned as the `root` user, the AppMap editor extension is unable to index them, which is necessary for them to be visible in the code editor extension.
+
+We recommend reviewing the [Docker official documentation regarding bind mounts](https://docs.docker.com/storage/bind-mounts/) for the most up to date information on the permission settings for linux bind mounts.  
+
+As a Linux user, make sure that the user/group you are running VS Code as also has write access.  For more info, refer to [this blog post](https://techflare.blog/permission-problems-in-bind-mount-in-docker-volume/) which goes into detail about Linux, Docker, and file permissions.

package/built/docs/integrations/github-actions.md

@@ -0,0 +1,24 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: GitHub Actions
+step: 2
+---
+
+# GitHub Actions
+
+<p class="alert alert-info">
+To get started with the AppMap GitHub Action,  <a href="/docs/setup-appmap-in-ci/in-github-actions">refer to the setup documentation</a>
+</p>
+
+AppMap Analysis can work within GitHub Actions to collect, store, analyze, and report on the behavioral changes within each Pull Request. AppMap will analyze the changes in your application on each pushed commit or pull request. AppMap performs a thorough analysis of the runtime differences, giving you:
+
+Root cause analysis of failed tests.
+Web service API changes, both breaking and non-breaking.
+New and resolved security findings.
+New and resolved performance findings.
+New and resolved findings in other categories: maintainability, reliability, and user-defined rules.
+“Behavioral diffs” as sequence diagrams showing changed runtime behavior within the PR.
+
+Refer to the [Getting Started with GitHub Actions Documentation](/docs/setup-appmap-in-ci/in-github-actions.html) to learn more about how to integrate GitHub Actions with AppMap

package/built/docs/integrations/index.md

@@ -0,0 +1,17 @@
+---
+layout: docs
+title: Docs - Integrations
+toc: false
+---
+
+# Integrations
+
+AppMap supports integrations with many popular servcies. Learn more about how to integrate AppMap with other services.
+
+- [Atlassian Compass](/docs/integrations/atlassian-compass)
+- [Atlassian Confluence](/docs/integrations/atlassian-confluence)
+- [GitHub Actions](/docs/integrations/github-actions)
+- [PlantUML](/docs/integrations/plantuml)
+- [Postman](/docs/integrations/postman)
+- [SmartBear SwaggerHub](/docs/integrations/smartbear-swaggerhub)
+- [Readme.com](/docs/integrations/readme)

package/built/docs/integrations/plantuml.md

@@ -0,0 +1,65 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: PlantUML
+step: 3
+---
+
+# PlantUML
+
+AppMap can generate sequence diagrams in the PlantUML format, a textual format which is portable and easy to modify. This lets you integrate with other tools that support the Mermaid or PlantUML syntax. You can touch up the generated diagrams, and copy-paste the diagram text into a wide variety of tools that support the PlantUML format, such as Atlassian Confluence.
+
+There are two ways to generate a PlantUML sequence diagram:
+
+1. Run the `sequence-diagram` command with the option `--format plantuml`
+1. Generate a sequence diagram from the code editor. Then locate the sequence diagram file in the file tree, and you’ll see a `<name>.sequence.uml` file.
+
+You can copy the file contents directly into other tools, or you can customize it first like. If you are going to edit the PlantUML file, be sure and save it as a new file first.
+
+### Generating sequence diagrams from the CLI
+
+AppMaps can be generated on the command line from your terminal, or within a CI build.
+
+#### CLI command: `sequence-diagram`
+
+You can generate sequence diagrams using the AppMap CLI command `sequence-diagram`.
+
+An example:
+
+```
+$ appmap sequence-diagram --format plantuml tmp/appmap/minitest/Following_followers_page.appmap.json
+```
+
+### Comparing sequence diagrams
+
+When two AppMaps are similar, it can be useful to represent them as sequence diagrams and then compare them. This is most useful:
+
+1. To compare AppMaps of two different test cases, requests, or remote recordings.
+1. To compare two different versions of the same AppMap - before and after a code change.
+
+Sequence diagram comparisons can be attached to GitHub Pull Requests to make it easier for reviewers to better understand changes in code.
+
+#### CLI command: `sequence-diagram-diff`
+
+The `sequence-diagram-diff` command takes two diagram files as arguments, and produces a comparison file of the differences between them. For example: 
+
+```
+$ appmap sequence-diagram-diff --format plantuml user-search-1.sequence.json user-search-2.sequence.json
+```
+
+Note: this command takes sequence diagram files as arguments, not AppMap files. To convert an AppMap file to sequence diagram format, use this command:
+
+```
+$ appmap sequence-diagram -f json user-search-1.appmap.json
+```
+
+#### Comparing Sequence Diagrams in VS Code 
+
+Download the PlantUML JAR file from [https://plantuml.com/download](https://plantuml.com/download)
+
+Configure the file location:
+
+<img class="video-screenshot" src="/assets/img/sequence-diagrams/plant-uml-location.png"/> 
+
+<img class="video-screenshot" src="/assets/img/sequence-diagrams/compare.png"/> 

package/built/docs/integrations/postman.md

@@ -0,0 +1,29 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: Postman
+step: 4
+---
+
+# Postman
+
+After generating your OpenAPI definitions you can import to [Postman](https://www.postman.com/) 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. 
+
+<img class="video-screenshot" src="/assets/img/openapi/postman-1.png"/> 
+
+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. 
+
+<img class="video-screenshot" src="/assets/img/openapi/postman-2.webp"/> 
+
+After Postman validates your OpenAPI definition, you can adjust any advanced settings or accept the default import settings. 
+
+<img class="video-screenshot" src="/assets/img/openapi/postman-3.png"/> 
+
+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. 
+
+<img class="video-screenshot" src="/assets/img/openapi/postman-4.png"/> 
+
+Refer to the [Postman documentation](https://learning.postman.com/docs/getting-started/introduction/) for additional details on using Postman to interact with your APIs. 

package/built/docs/integrations/readme.md

@@ -0,0 +1,38 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: Readme
+step: 6
+---
+
+# Readme
+
+[Readme](https://readme.com/) 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. 
+
+<img class="video-screenshot" src="/assets/img/readme-api-documentation.webp"/> 
+
+Simply access your Readme administration page, and go to _API Settings_ to add a new endpoint. 
+
+<img class="video-screenshot" src="/assets/img/readme-github-action.webp"/> 
+
+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.](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
+
+```
+- name: Install rdme
+  run: npm install rdme@latest -g
+- name: Install AppMap tools
+  uses: getappmap/install-action@v1
+- name: AppMap Generate OpenAPI Definitions
+  run: appmap openapi --output-file openapi.yml
+- name: Push OpenAPI to Readme
+  run: rdme openapi openapi.yml --version=v1.0 --key="${{ secrets.RDME_KEY }}"
+```
+
+After your build job completes you'll see your API imported into Readme.
+
+<img class="video-screenshot" src="/assets/img/readme-openapi-imported.png"/> 
+
+And when navigating into any of your API endpoints, you'll see notifications that this API is _synced from Swagger.
+
+<img class="video-screenshot" src="/assets/img/readme-openapi-synced.png"/> 

package/built/docs/integrations/smartbear-swaggerhub.md

@@ -0,0 +1,125 @@
+---
+layout: docs
+title: Docs - Integrations
+integrations: true
+name: SmartBear SwaggerHub
+render_with_liquid: false
+step: 5
+---
+
+# SmartBear SwaggerHub and Portal
+
+[SwaggerHub](https://swagger.io/tools/swaggerhub/) is a centralized API design tool which allows teams to collaborate on API design and enforce style, quality, and consistency of their APIs. 
+
+[SwaggerHub Portal](https://swagger.io/tools/swaggerhub/features/swaggerhub-portal/) let's you synchronize your API designs from SwaggerHub into a customized portal which creates comprehensive and easy to use API documentation for your users and customers.  
+
+AppMap supports multiple use-cases when integrating AppMap and SwaggerHub.
+- [Generate Code-First OpenAPI and Publish to SwaggerHub](#generate-code-first-openapi-and-publish-to-swaggerhub)
+- [Disable Deployment when Runtime OpenAPI Diverges from SwaggerHub API](#disable-deployment-when-runtime-openapi-diverges-from-swaggerhub-api)
+  
+## Generate Code-First OpenAPI and Publish to SwaggerHub
+
+AppMap supports the integration of it's automatic code-first OpenAPI documentation functionality directly into the SwaggerHub platform by leveraging the [SwaggerHub CLI](https://github.com/SmartBear/swaggerhub-cli) and GitHub Actions.  Using AppMap, you can automated interact with your API routes via a GitHub action, AppMap will automatically capture details about those API route interactions and export them into OpenAPI supported formats. From there, you can use the SwaggerHub CLI to push these APIs directly to SwaggerHub and Portal. 
+
+### Configuration
+
+First, access your API key on the [user settings page](https://app.swaggerhub.com/settings/apiKey) in SwaggerHub. When using GitHub Actions, you'll want to save this API key as a [action secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) named `SWAGGERHUB_API_KEY`.
+
+Add the relevant commands to your GitHub Action or your CI system. Make sure you export the SwaggerHub API key as a build environment variable in the action.
+
+```
+env:
+  SWAGGERHUB_API_KEY: ${{ secrets.SWAGGERHUB_API_KEY }}
+```
+
+```
+- name: Install SmartBear CLI
+  run: npm i -g swaggerhub-cli 
+- name: Install AppMap tools
+  uses: getappmap/install-action@v1
+
+- name: Set API Version Number
+  run: echo "OPENAPI_VERSION"=$(cat openapi-version) >> "$GITHUB_ENV"
+
+- name: Generate OpenAPI with AppMap
+  run: appmap openapi --output-file openapi.yml --openapi-title <repo name> --openapi-version ${OPENAPI_VERSION}
+
+- name: Publish API to SmartBear
+  run: swaggerhub api:create <swaggerhub team>/<repo name> --file openapi.yml
+
+- name: Set Latest API Default
+  run: swaggerhub api:setdefault <swaggerhub team>/<repo name>/${OPENAPI_VERSION}
+```
+
+Refer to [this project on GitHub](https://github.com/land-of-apps/rails_tutorial_sample_app_7th_ed/blob/smartbear-integration/.github/workflows/openapi-publish.yml) for a fully working example of this GitHub Action.
+
+After your build job completes, you'll see your latest version of your API imported into SwaggerHub. 
+
+<img class="video-screenshot" src="/assets/img/swaggerhub-api.webp"/> 
+
+Next, navigate to your SwaggerHub Portal administration page, select on your project and find the latest release of the uploaded API. 
+
+<img class="video-screenshot" src="/assets/img/swaggerhub-portal-link.webp"/>
+
+When you are ready to publish this API to your users and customers, simply click the "Link API" button. 
+
+<img class="video-screenshot" src="/assets/img/swaggerhub-publish.webp"/>
+
+After it's published, you'll see the latest revision now available in your SwaggerHub Portal
+
+<img class="video-screenshot" src="/assets/img/swaggerhub-portal.webp"/>
+
+### Demo
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0;"><iframe src="https://www.loom.com/embed/b36735e6254a4a13a824c827a3390efb" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
+
+## Disable Deployment when Runtime OpenAPI Diverges from SwaggerHub API
+
+Because we are going to be using the SwaggerHub CLI inside of our CI/GitHub action
+
+### Configuration
+Because we are going to be using the SwaggerHub CLI inside of our CI/GitHub action you'll need to store the API key as an [encrypted secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) in your GitHub action.
+
+Access your API key on the [user settings page](https://app.swaggerhub.com/settings/apiKey) in SwaggerHub. Store this as an encrypted secrete named `SWAGGERHUB_API_KEY`.
+
+Add the relevant commands to your GitHub Action or your CI system. Make sure you export the SwaggerHub API key as a build environment variable in the action.
+
+```
+env:
+  SWAGGERHUB_API_KEY: ${{ secrets.SWAGGERHUB_API_KEY }}
+```
+
+```
+- name: Install SmartBear CLI
+  run: npm i -g swaggerhub-cli 
+- name: Install AppMap tools
+  uses: getappmap/install-action@v1
+
+- name: Set API Version Number
+  if: always() 
+  run: echo "OPENAPI_VERSION"=$(cat openapi-version) >> "$GITHUB_ENV"
+
+- name: Generate OpenAPI with AppMap
+  run: appmap openapi --output-file openapi.yml --openapi-title <repo name> --openapi-version ${OPENAPI_VERSION}
+
+- name: Get Latest Default
+  if: always()
+  run: swaggerhub api:get <swaggerhub team>/<repo name> > swaggerhub-api.yml
+
+- name: Normalize OpenAPI Files
+  if: always()
+  run: cat openapi.yml | sed '/^$/d' > openapi-clean.yml && cat swaggerhub-api.yml | sed '/^$/d' > swaggerhub-clean.yml
+
+- name: Compare Actual vs SwaggerHub
+  if: always()
+  run: diff openapi-clean.yml swaggerhub-clean.yml 
+```
+
+Refer to [this project on GitHub](https://github.com/land-of-apps/rails_tutorial_sample_app_7th_ed/blob/smartbear-api-comparison/.github/workflows/openapi-compare.yml) for a fully working example of this GitHub Action.
+
+With this configuratino enabled, when a user makes a commit which changes the routes that are NOT currently in the published API spec on SwaggerHub this build will fail and the user will be unable to deploy unless they update the API spec on SwaggerHub or remove the offending changes. 
+
+<img class="video-screenshot" src="/assets/img/swaggerhub-github-build-failure.webp"/>
+
+### Demo
+<div style="position: relative; padding-bottom: 56.25%; height: 0;"><iframe src="https://www.loom.com/embed/f51d590a46e8493ebb27be33c63328e6" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>