Skip to content

Latest commit

 

History

History
75 lines (54 loc) · 3.48 KB

CONTEXT.md

File metadata and controls

75 lines (54 loc) · 3.48 KB

APIMatic CLI

The command-line client that validates API specifications, generates SDKs, and builds documentation portals from a user's src/ directory.

Language

Portal build

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

Code samples

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 regeneration

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