@appland/appmap 3.146.0 → 3.147.0

package/built/docs/integrations/readme.md

@@ -0,0 +1,39 @@
+---
+layout: docs
+title: Docs - Integrations
+description: "Optimize your AppMap API interaction with Readme's developer hub. Easily add new endpoints and sync with your GitHub Action or CI system for efficient documentation."
+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,119 @@
+---
+layout: docs
+title: Docs - Integrations
+description: "AppMap integration with SwaggerHub automates API documentation directly into SwaggerHub using GitHub Actions. Collaborate on API design, ensuring style, quality, and consistency."
+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"/>
+
+## 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"/>

package/built/docs/reference/analysis-labels.md

@@ -0,0 +1,49 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Explore technical documentation for analysis labels with AppMap."
+name: Analysis Labels
+step: 14
+reference: true
+redirect_from: [/docs/analysis/labels-reference]
+---
+
+# Label Reference
+<ul class="toc">
+{% for analysis_label in site.analysis_labels %}
+  <li>
+    <a href="#{{ analysis_label.name }}">{{analysis_label.name }}</a>
+  </li>
+{% endfor %}
+</ul>
+
+
+<ul class="analysis-doc-list label">
+  {% for analysis_label in site.analysis_labels %}
+    <li class="analysis-label" id="{{ analysis_label.name }}">
+      <h2>
+        {{ analysis_label.name }}
+      </h2>
+
+      <div class="analysis-metrics">
+        <ul>
+          <li class="name">Rules</li>
+          <li class="value">
+            {% for rule in analysis_label.rules %}
+              <a href="./analysis-rules.html#{{rule}}">
+                {{ rule }}
+              </a>
+              <br/>
+            {% endfor %}
+          </li>
+        </ul>
+      </div>
+
+      {{ analysis_label.content | markdownify }}
+    </li>
+    <hr/>
+{% endfor %}
+</ul>  
+
+
+

package/built/docs/reference/analysis-rules.md

@@ -0,0 +1,61 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Explore detailed rules reference for AppMap analysis, including impact, scope, labels, and references."
+name: Analysis Rules
+step: 14
+reference: true
+---
+
+# Rules Reference
+<ul class="toc">
+{% for analysis_rule in site.analysis_rules %}
+  <li>
+    <a href="#{{ analysis_rule.rule }}">{{analysis_rule.name }}</a>
+  </li>
+{% endfor %}
+</ul>
+
+<ul class="analysis-doc-list">
+{% for analysis_rule in site.analysis_rules %}
+  <li class="analysis-rule" id="{{ analysis_rule.rule }}">
+    <h2>
+      {{ analysis_rule.name }}
+    </h2>
+
+    <div class="analysis-metrics">
+      <ul>
+        <li class="name">Id</li>
+        <li class="value">{{ analysis_rule.rule }}</li>
+      </ul>
+      <ul>
+        <li class="name">Impact Domain</li>
+        <li class="value">{{ analysis_rule.impactDomain }}</li>
+      </ul>
+      <ul>
+        <li class="name">Scope</li>
+        <li class="value">{{ analysis_rule.scope }}</li>
+      </ul>
+      <ul>
+        <li class="name">Labels</li>
+        <li class="value">
+          {% for label in analysis_rule.labels %}
+            <a href="./analysis-rules.html#{{ label }}">{{ label }}</a>
+            <br/>
+          {% endfor %}
+        </li>
+      </ul>
+      <ul>
+        <li class="name">References</li>
+        <li class="value">
+          {% for reference in analysis_rule.references %}
+            <a href="{{ reference[1] }}" target="_blank">{{ reference[0] }}</a>
+          {% endfor %}
+        </li>
+      </ul>
+    </div>
+    {{ analysis_rule.content | markdownify }}
+  </li>
+  <hr/>
+{% endfor %}
+</ul>