Importing a spec

Importing turns an OpenAPI spec into resources and operations. Re-importing a newer version diffs it against your current spec and shows the impact before changing anything.

First import

In the app, the New API wizard imports the spec and walks you through the mapping. From the CLI:

craftr schema import https://petstore3.swagger.io/api/v3/openapi.json -a petstore-api

The source can be a URL or a file path; omit it to read from a saved source or piped stdin. The source you pass is saved in api.json (specSource) for future re-imports.

The diff report

Before applying, API Craft reports what will change, in four groups:

• Operation changes: added, removed, modified, and anything that lands unmapped. Added operations are auto-mapped where the heuristics can; removed ones are flagged (and noted if a request or rule references them).
• Override outcomes: how your edits interact with the new spec: noChange, caughtUp (the source now matches your override, so it can be dropped), conflicts (the field changed in both), and orphans (your override targets something that's gone).
• Defined-operation conflicts: a locally-defined operation that now exists in the source spec.
• Orphan rules: mapping rules whose match no longer resolves.

On a terminal the import is interactive: you resolve each item, then confirm. Pass --yes to skip the confirmation (required for non-interactive use), and preview without importing with:

craftr schema diff -a petstore-api          # against the saved source
craftr schema diff ./new-spec.yaml -a petstore-api

Resolving the diff

Handling unmapped operations

Whatever the heuristics can't place lands as unmapped. Map or ignore it:

craftr schema unmapped -a petstore-api               # see what's unmapped
craftr schema map updatePetWithForm Pet updateWithForm -a petstore-api
craftr schema ignore uploadFile -a petstore-api
craftr schema map-all --default -a petstore-api      # bulk-map everything by heuristic

You can do the same visually from the schema sidebar in the app.