Skip to content

v2.0.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 26 Oct 08:30
v2.0.0
ad7873b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

2.0.0 (2026-10-26)

In 2.0 the CLI builds documentation portals on your machine, configures a project from a single src/apimatic.json, adds SDK and Context Plugin pages and code samples to a portal, and generates SDKs with the v4 generator.

Note

npm install -g @apimatic/cli now installs 2.0. A 1.x project needs the changes below before 2.0 can build it. To stay on 1.x for now, install @apimatic/cli@1, and in CI run npx @apimatic/cli@1: a pipeline that runs npx @apimatic/cli without a version gets 2.0 from now on.

Breaking changes

To move a 1.x project over, work through this list.

  • Node.js 24 or newer is required. On an older Node the CLI stops at startup and names the version it found. (#347)
  • Portals are built on your machine from src/. OpenAPI documents go in src/spec/, Markdown pages in src/content/, and images and other files in src/static/. Preview the portal with apimatic portal serve and build it with apimatic portal generate. (#343)
    • src/apimatic.json configures the portal. APIMATIC-BUILD.json no longer does. A minimal file: 
      {
  "$schema": "https://cdn.jsdelivr.net/npm/@apimatic/cli@2/apimatic.schema.json",
  "schemaVersion": 1,
  "portal": {
    "site": { "name": "Acme API" }
  },
  "languages": {
    "typescript": {}
  }
}
      site also takes url and description, and the portal block takes brand (logo, favicon, colours and colour mode), navigation (header links) and ai (page actions). The $schema line lets your editor complete and check the file. To see every key with its default, run apimatic quickstart in an empty directory. (#348, #355)
    • languages names at least one SDK language: csharp, python or typescript.
    • Every page needs front matter with a title, which names it in the sidebar. The CLI lists the pages that lack one before it builds. 
      ---
title: Getting started
---
    • HTML and components work only in .mdx pages. In a .md page, HTML tags such as <img>, <br>, <div> or <details>, and components such as 1.x's <CardGroup> or <AccordionGroup>, are left out of the built page, with no warning. Text on the same lines as a dropped tag goes with it; text separated from it by blank lines stays. Rename such a page to .mdx, close empty tags (<br />, <img … />), and use 2.0's components, for example <Cards> with <Card href="…">, and <Accordions> with <Accordion>.
    • nav.json replaces toc.yml. A nav.json beside your pages lists them in order by file name, and its title names their folder. In src/content/nav.json, tabs names the tabs after Home, in order: a folder directly under src/content/, or a section the CLI makes (apimatic:api, apimatic:sdks, apimatic:plugin). Without tabs the portal has no tab bar. (#346, #371, #408) 
      {
  "tabs": ["guides", "apimatic:sdks", "apimatic:api"],
  "pages": ["index", "..."]
}
    • OAuth sign-in in the API playground returns to /oauth/callback on the portal's address. Register that redirect URI with your OAuth provider, for example https://docs.example.com/oauth/callback. (#424)
    • Versioned portals are not supported. A project that builds several API versions from versioned_docs/ (generateVersionedPortal in APIMATIC-BUILD.json) can't be built with 2.0, so keep it on @apimatic/cli@1. (#343)
  • src/apimatic.json replaces plugin-config.json. Its plugin block holds the plugin's identity. plugin-config.json is no longer read, so run plugin generate and sdk publish again after upgrading, then delete it. (#348)
  • Some portal commands are removed. portal toc new, portal recipe new and portal copilot are gone, and portal serve no longer takes --destination or --no-reload. Run apimatic autocomplete --refresh-cache to drop them from shell completion. (#343)
  • SDKs are generated with v4 only. (#359)
    • --codegen-version on sdk generate and sdk publish accepts only v4, which is now the default.
    • C#, Python and TypeScript can be generated today. Java, Ruby, PHP and Go come back as v4 supports them.
    • apimatic sdk save-changes is removed, along with --track-changes and --skip-changes on sdk generate.
    • sdk publish no longer takes --update-plugin-config. Every publish records itself in src/apimatic.json.
  • apimatic quickstart always builds a portal. It no longer offers an SDK instead. Use apimatic sdk generate for an SDK on its own. (#363)

Upgrading from a 2.0 beta

  • Install with npm install -g @apimatic/cli from now on. @beta installs the next 2.x prerelease once one is out.
  • Point $schema in src/apimatic.json at https://cdn.jsdelivr.net/npm/@apimatic/cli@2/apimatic.schema.json. The @beta address keeps following the newest prerelease. (#450)
  • .apimatic-build/ folders that earlier betas left beside src/ are no longer used and can be deleted. (#440)
  • From beta.1 or beta.2, also follow the upgrade notes of 2.0.0-beta.3 and 2.0.0-beta.5. From beta.3 or beta.4, those of 2.0.0-beta.5.

Features

  • api: flagless api validate and quickstart avoids mutating adopted projects (#405) (abed462)
  • code samples support (#352) (7b82568)
  • config: replace portal.json and plugin-config.json with apimatic.json (#348) (506f67f)
  • local plugin generation (#358) (5ba70de)
  • portal: a tabs key in the root nav.json (#408) (9fcf772)
  • portal: build a portal from the spec folders APIMATIC-META.json merges (#435) (0faa568)
  • portal: build the documentation portal locally with Fumadocs (#343) (073d09a)
  • portal: build the SDK and Context Plugin pages from real templates and the portal artifacts (#369) (0efd7b3)
  • portal: fetch the artifacts from /portal-artifacts (#361) (0e823f3)
  • portal: generate the SDK and context plugin pages (#360) (338b14a)
  • portal: give the portal block its v2 shape, with branding and tabs (#355) (d0fb189)
  • portal: host a portal under the path of site.url (#411) (767671b)
  • portal: lead each SDK card with its install command (#376) (119e9d6)
  • portal: let content pages use Fumadocs' Tabs, Steps, Accordions and other components (#439) (633b81d)
  • portal: let the root nav.json decide the tabs, and fix the nav.json QA findings (#371) (ecf7666)
  • portal: one OAuth redirect URI for every endpoint page (#424) (876e66c)
  • portal: order the sidebar from nav.json (#346) (306e4f9)
  • portal: point to api transform when src/spec has no OpenAPI 3.x document (#364) (eefc917)
  • portal: the SDK Overview design, on the SDKs, language and plugin pages (#391) (fd3fe34)
  • quickstart: suggest validating with an AI agent when a spec fails (#385) (36fd2bb)

Fixes since 1.5.0

  • Validation errors the server reports during plugin generate print as plain text rather than raw HTML. (#375)
  • The interactive sdk publish asks "Do you want to proceed?" with No selected, so pressing Enter no longer starts a publish. (#375)
  • api validate and api transform given a --file that does not exist or cannot be read say so, instead of ending with an ENOENT error. (#405)
  • When sdk generate or plugin generate cannot unzip what it downloaded, or sdk generate --zip cannot write its zip, the command stops with a message and the reason, instead of an uncaught error. (#415)
  • The sign-in hint after a 401 gives the whole command, apimatic auth login --auth-key={api-key}. (#425)
Assets 2
Loading