RabbinatixDocs
Sign inGet started

Map your systems

Import and export

Bring in OpenAPI, Postman, Pact and browser recording (HAR) files, sync again when they change, and export OpenAPI and Pact.

Open Import in the app

What you can import

SourceBecomesNotes
OpenAPI 3 or Swagger 2, JSON or YAMLProvider endpointsReferences, allOf, oneOf and anyOf are read
Pact file (v3 or v4)Consumer expectationsKeep your Pact tests as they are
Postman collection v2.1Consumer expectationsBodies come from saved examples
Browser recording (HAR file)Consumer expectationsRecord your frontend in DevTools; the calls it made become its expectations

Import a file

  1. Press New beside search, then Import. On the map you can also choose Import OpenAPI / HAR from the toolbar's more menu.
  2. Paste the file into Paste JSON or YAML, or drop a file, drop it there, or press Choose file. To try it out, press Load sample on a format.
  3. Press Analyze. The review shows the format it found and how many endpoints it read.
  4. Choose the system the endpoints belong to, or create a new one from the list.
  5. For expectations, choose the Provider they call. For HAR and Postman files with several hosts, use Map each host to a provider system. Choose Skip for a host you don't want.
  6. Check the table, then press the import button. It says how many endpoints it will import.
  7. Import complete shows what was added. Every contract was checked straight away. Press View on map.
NoteA HAR file can hold tokens and cookies. The importer drops the values of auth headers and never stores secrets.

OpenAPI details

  • $ref references are resolved and allOf parts are merged.
  • oneOf and anyOf stay as a choice of shapes. When the side that sends may send several shapes, the receiver must take each of them, and a mismatch says which option it is about.
  • In Swagger 2, an in: body parameter is the request body. in: formData parameters become a form body, with files as binary strings.

Import again to sync

When your spec changes, import it again into the same system. The import becomes a sync:

  • The summary line reads "Sync with" the system, then counts new, changed, unchanged and not in this file.
  • Each changed endpoint opens to its list of changes, each marked breaking, additive or neither. If it breaks consumers, it says how many and why.
  • Not in this file lists endpoints the system has but the file doesn't. Tick the ones to remove. The rest stay as they are.
  • Press Apply changes.

A changed endpoint keeps its identity, so its history carries on. If the file is the same as the system, you see "Everything in this file is already up to date."

TipA large import is saved in parts. If it stops part way, what was saved stays. Apply again: only what is missing or changed is written.

Export OpenAPI

  1. Open the provider system's Settings tab.
  2. Press Export OpenAPI.
  3. Under Export, choose The system now or one of its releases.
  4. Press Copy or Download.

The document is OpenAPI 3.1. Its info.version is the release, or a prerelease such as 1.4.0-next.3 when the system changed since its newest release. An x-rabbinatix block records the system, the release and a hash of the content.

Copying or downloading records the export. The next time you open it, it says "Same as" or "Changed since" the last export, with one line per changed endpoint marked Big change, Addition or Fix.

Export Pact

  1. Open the connection between the consumer and the provider.
  2. Choose Export Pact from the more menu.
  3. Press Copy.

The Pact file holds the consumer's expectations of that provider, so a team can keep running Pact verification. How the two compare and work together: Pact and Rabbinatix.

Check a copy later

Every OpenAPI export can be checked: paste it into Check my copy on the Releases page (pick the system) to see whether it is still current and what changed since. See Versions and releases.