The command-line client that validates API specifications, generates SDKs, and builds documentation portals from a user's src/ directory.
Source directory:
The user's src/ directory — apimatic.json, spec/, content/, static/ — taken as the input to every portal and SDK run, and never written to.
Avoid: Build directory, project, workspace, source folder
Project directory: The directory that contains the source directory. Avoid: Build directory, project root
Portal project: The throwaway site assembled for one portal run from the portal template, the source directory and the portal artifacts, and discarded once the run ends. Avoid: Build directory, build project, build tree
Spec:
One API description in spec/, in any format APIMatic can transform (OpenAPI 3.x, Swagger, Postman Collections, RAML, API Blueprint, etc.), which becomes one section of reference pages in the portal.
Avoid: Specification file, API definition
Spec directory:
The spec/ directory in the source directory: every spec, the files they reference, and anything else kept beside them.
Avoid: Specs folder, spec folder
Endpoint: An operation addressed by its HTTP method and path template, exactly as the spec writes them. Avoid: Operation ID, route
Portal artifacts: Everything the APIMatic platform generates for one portal build — SDKs, SDK docs, code-sample catalogs and the context plugin — delivered together as one zip. Avoid: Generation output, SDK bundle
SDK docs: One language's documentation pages, such as "Getting Started", written for that language's SDK. Avoid: Language guide, language docs, docs
Code-sample catalog: One language's code samples for every endpoint of the source directory, keyed by endpoint then by example id. Avoid: Snippet file, samples JSON
Code sample: One language's snippets for one endpoint, each tied to an example id, shown as one tab on the operation page. Avoid: Snippet, usage, request sample
Example id:
The key of an OpenAPI examples: entry — the request body's, else the first parameter's that names any — which pairs a snippet with the example the portal's selector shows.
Avoid: Example name, variant
Unplaced sample: A code sample whose endpoint no spec in the source directory declares. Avoid: Orphan sample, missing operation
SDK directory:
The directory sdk generate and sdk publish write an SDK into, and read back on every later run: the --destination itself when one is named, else <input>/sdk/<language>.
Avoid: Destination, output directory, language directory
Pristine snapshot:
One generation's output exactly as the server returned it, stored as a commit under the hidden ref refs/apimatic/pristine of the SDK directory's own repository, never on a branch; the base of the next merge.
Avoid: Generated snapshot, baseline, original
Generation record:
<sdk>/.apimatic/generation.json, committed with the SDK, naming the pristine snapshot the directory was last written from. Written with .apimatic/.gitattributes beside it, so git merges it as binary and GitHub collapses it in pull requests.
Avoid: Lock file, manifest, metadata file
Custom code: Whatever differs between the SDK directory on disk and its pristine snapshot: the developer's edits, additions, deletions and moves, kept by merging the next generation over them. Avoid: Customizations (in code), user changes, overrides