Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .ai/instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ pnpm apimatic <command> -i <abs-path-to-dir-containing-src> # -i: for commands

`pnpm-workspace.yaml` sets `minimumReleaseAge: 10080` (7 days) as a supply-chain defense. Brand-new package versions are blocked from install until they've been on the registry for at least a week. `@apimatic/*` is exempt via `minimumReleaseAgeExclude`.

If you hit `ERR_PNPM_PACKAGE_RECENTLY_PUBLISHED` adding a fresh release, either wait it out or run a one-off install with `pnpm install --ignore-minimum-release-age` (CI uses `--frozen-lockfile`, which bypasses the check entirely, so this only blocks manual `pnpm add` / `pnpm update`).
If you hit `ERR_PNPM_PACKAGE_RECENTLY_PUBLISHED` adding a fresh release, either wait it out or run a one-off install with `pnpm install --config.minimumReleaseAge=0` (pnpm 11 has no `--ignore-minimum-release-age` flag; CI uses `--frozen-lockfile`, which bypasses the check entirely, so this only blocks manual `pnpm add` / `pnpm update`).

## TypeScript toolchain — two compilers, on purpose

Expand Down
32 changes: 32 additions & 0 deletions .github/workflows/portal_tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,16 @@ on:
push:
branches: [dev]

# A branch of the test suite can be named when a CLI change moves what the
# suite checks, so the two can be run together before either lands. A push
# to dev always runs the suite's main.
workflow_dispatch:
inputs:
tests_ref:
description: Branch, tag or SHA of apimatic/v4-test-automation to run
required: false
default: main
type: string

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
Expand Down Expand Up @@ -82,6 +91,7 @@ jobs:
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
repository: apimatic/v4-test-automation
ref: ${{ inputs.tests_ref || 'main' }}
path: tests

- name: install test dependencies
Expand Down Expand Up @@ -200,6 +210,28 @@ jobs:
PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}\.playwright-browsers
run: pnpm test:functional

# Functional against the suite's petstore build: server selection, server
# variables and request parameters on the playground
# (tests/functional/petstore/). The tests intercept their own calls, so
# this needs no API Tester and no secrets beyond generation.
- name: generate the petstore portal
id: generate-petstore
if: ${{ !cancelled() }}
working-directory: tests
env:
PORTAL: petstore
run: pnpm portal:generate

- name: functional — petstore
if: ${{ !cancelled() && steps.generate-petstore.outcome == 'success' }}
working-directory: tests
shell: bash
env:
PORTAL: petstore
PORTAL_PREBUILT: '1'
PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}\.playwright-browsers
run: pnpm test:functional

- name: upload playwright report
if: ${{ !cancelled() }}
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,14 +298,15 @@ Generate a static API Documentation Portal.

```
USAGE
$ apimatic portal generate [--zip] [-i <value>] [-d <value>] [-f] [-k <value>]
$ apimatic portal generate [--zip] [--no-analytics] [-i <value>] [-d <value>] [-f] [-k <value>]

FLAGS
-d, --destination=<value> [default: <input>/portal] path where the portal will be generated.
-f, --force overwrite changes without asking for user consent.
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes
API specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
--no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'.
--zip write the generated portal as a .zip archive.

DESCRIPTION
Expand Down Expand Up @@ -338,14 +339,15 @@ Preview your API Documentation Portal with live reload.

```
USAGE
$ apimatic portal serve [-p 23513] [-o] [-i <value>] [-k <value>]
$ apimatic portal serve [-p 23513] [-o] [--no-analytics] [-i <value>] [-k <value>]

FLAGS
-i, --input=<value> [default: ./] path to the parent directory containing the 'src' directory, which includes API
specifications and configuration files.
-k, --auth-key=<value> override current authentication state with an authentication key.
-o, --open open the portal in the default browser.
-p, --port=23513 [default: 23513] port to serve the portal on.
--no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'.

DESCRIPTION
Preview your API Documentation Portal with live reload.
Expand Down
73 changes: 73 additions & 0 deletions apimatic.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,79 @@
}
}
},
"analytics": {
"type": "object",
"description": "Analytics the portal loads. Every page view goes to window.dataLayer as docs_page_view, and to GA4 when a measurement ID is set.",
"additionalProperties": false,
"properties": {
"googleTagManager": {
"type": "object",
"additionalProperties": false,
"required": ["containerId"],
"properties": {
"containerId": {
"allOf": [
{
"$ref": "#/definitions/nonBlank"
}
],
"description": "The container's ID, for example 'GTM-ABC123'."
},
"environment": {
"type": "object",
"description": "A GTM environment, for a staging build only, which loads the container's staging version: the gtm_auth and gtm_preview values from the environment's snippet. Both are public in the built portal, so a production portal sets none.",
"additionalProperties": false,
"required": ["auth", "preview"],
"properties": {
"auth": {
"$ref": "#/definitions/nonBlank"
},
"preview": {
"$ref": "#/definitions/nonBlank"
}
}
}
}
},
"googleAnalytics": {
"type": "object",
"additionalProperties": false,
"required": ["measurementId"],
"properties": {
"measurementId": {
"allOf": [
{
"$ref": "#/definitions/nonBlank"
}
],
"description": "The GA4 web stream's measurement ID, for example 'G-ABC123'. The portal sends its own page views, so turn off the stream's 'Page changes based on browser history events'. Don't also add a GA4 tag to the GTM container: every hit would count twice."
}
}
},
"keepQueryParams": {
"type": "array",
"description": "Your own link tags to keep in reported page addresses. Campaign (utm_), ad-click and cross-domain tags are kept already; every other query parameter is dropped.",
"items": {
"$ref": "#/definitions/nonBlank"
}
}
}
},
"seo": {
"type": "object",
"description": "Search engine settings.",
"additionalProperties": false,
"properties": {
"googleSiteVerification": {
"allOf": [
{
"$ref": "#/definitions/nonBlank"
}
],
"description": "The content value of Google's site verification meta tag, for Search Console. Not needed for a Domain property verified by DNS."
}
}
},
"pluginUrl": {
"type": "string",
"description": "Where the context plugin is hosted, starting with 'https://' and with no spaces. The Context Plugin page installs it from here, and the portal carries no copy of its own.",
Expand Down
10 changes: 5 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,13 @@
"fast-levenshtein": "^3.0.0",
"form-data": "^4.0.2",
"fs-extra": "^11.3.0",
"fumadocs-core": "16.17.1",
"fumadocs-core": "16.18.0",
"fumadocs-mdx": "15.4.7",
"fumadocs-openapi": "12.1.1",
"fumadocs-ui": "16.17.1",
"fumadocs-openapi": "12.6.5",
"fumadocs-ui": "16.18.0",
"get-port": "^7.1.0",
"is-in-ci": "^2.0.0",
"lucide-react": "1.54.0",
"lucide-react": "1.71.0",
"mustache": "^4.2.0",
"neverthrow": "^8.2.0",
"open": "^8.4.0",
Expand All @@ -95,7 +95,7 @@
"remark": "15.0.1",
"remark-mdx": "3.1.1",
"semver": "^7.8.0",
"shiki": "4.5.0",
"shiki": "4.6.0",
"striptags": "^3.2.0",
"tailwindcss": "4.3.3",
"tmp-promise": "^3.0.3",
Expand Down
Loading
Loading