Import and Export

Importing OpenAPI specs

Create a collection of requests from an OpenAPI 3.0 or 3.1 spec.

Overview

An OpenAPI spec describes every operation an API offers. Relay turns a spec into a collection with a request for each operation, filled in with example parameters and bodies, the spec's authentication, and variables for the server address and credentials.

Relay imports OpenAPI 3.0 and 3.1 specs written in JSON or YAML, up to 20 MB. It doesn't import Swagger 2.0 specs; convert one to OpenAPI 3 first.

Import a spec

  1. Choose File > Import > OpenAPI Spec…. You can also click the Add button (+) at the bottom of the sidebar and choose Import > OpenAPI Spec….
  2. Choose where the spec comes from:
    • File: Drag a .json, .yaml or .yml file onto the sheet, or click Choose File….
    • URL: Enter the spec's address and click Fetch. Relay downloads it through the proxy set in the Network pane of Relay > Settings.
    • Paste: Paste the spec's text. If the clipboard holds a spec when you open the sheet, Relay pastes it for you.
  3. Check the Preview. It shows the spec's title and version, its server, how many requests and folders it creates, its authentication, the variables it adds, any warnings and the list of requests.
  4. Next to Import into, select New workspace or Existing workspace.
    • For a new workspace, enter a Workspace name.
    • For an existing workspace, choose it next to Workspace.
  5. Optionally, enter a Collection name. Both names default to the spec's title.
  6. Click Import.

Relay opens the new collection in the sidebar and selects its first request. To remove everything the import created, choose Edit > Undo.

You can also drag a spec file onto a Relay window. Relay reads it and opens the importer with the file already loaded.

If the document turns out to be a Postman collection or environment, the Preview says so. Click Import as Postman Collection to import it with the Postman importer instead.

Learn what the import creates

The import creates one collection, named after the spec's title:

  • Folders: Each operation goes in a folder named after its first tag, in the order the spec lists its tags. Operations without a tag go at the top of the collection. When every operation has the same tag, Relay doesn't create a folder.
  • Requests: Each request is named after the operation's summary, or its operationId, or else its method and path.
  • URLs: Each URL starts with {{baseUrl}} followed by the path. A path parameter with an example value is filled in; one without becomes a {{name}} placeholder you replace before sending. An operation that names its own server uses that server's URL instead of {{baseUrl}}.
  • Parameters: Query parameters, headers and cookies are filled in from the spec's examples or schemas. Optional ones are added turned off, with the spec's description, so you can turn on the ones you need. Cookie parameters are combined into one Cookie header.
  • Bodies: Relay picks the most useful content type an operation accepts, preferring JSON, then form fields, multipart forms and text. The body comes from the spec's example, or is generated from its schema. A binary upload becomes an empty Text body, and a body on a GET, HEAD or TRACE operation is left out.
  • Documentation: Each operation's summary, description, operationId, tags, deprecated flag and external documentation link appear in the request's Documentation tab. For more, see Documenting requests.

Variables

The import adds a baseUrl variable set to the spec's first server, with the server's variables filled in from their defaults. When the spec's server URL is relative, such as /v2, Relay resolves it against the address you fetched the spec from. When the spec has no server, or a relative one in a file, baseUrl needs your attention and the Preview warns you.

The import also adds an empty variable for each credential its security schemes need. These variables are marked secret, so their values stay on your Mac:

Security schemeVariables
HTTP bearerbearerToken
HTTP basic or digestusername, password
API keyapiKey
OAuth 2.0 with the authorization code or client credentials flow, or OpenID ConnectclientId, clientSecret
OAuth 2.0 with only the implicit or password flowaccessToken

When two schemes need the same variable, the second one's name ends with its scheme's name, as in apiKey_partnerKey.

In a new workspace, these become workspace variables. In an existing workspace, they become variables of the new collection, so they don't change the workspace's own variables. If an environment in that workspace defines a variable with the same name, the Preview tells you; the environment's value wins while it's active.

To start sending, fill in the credential variables. In a new workspace, choose Edit Workspaces… from the workspace menu and click Variables. In an existing workspace, Control-click the collection in the sidebar and choose Edit Variables…. For more, see Keeping secrets on your Mac.

Authentication

Relay maps each security scheme to one of its own authentication types, with the variables above in place of the credentials:

Security schemeRelay authentication
HTTP bearerBearer Token
HTTP basicBasic Auth
HTTP digestDigest Auth
API key in a header or query parameterAPI Key
API key in a cookieA Cookie header
OAuth 2.0 authorization code flowOAuth 2.0 with the authorization code grant and PKCE, the spec's endpoints and scopes
OAuth 2.0 client credentials flowOAuth 2.0 with the client credentials grant
OAuth 2.0 with only the implicit or password flowBearer Token
OpenID ConnectOAuth 2.0 without endpoints

The spec's top-level security becomes the workspace's authentication in a new workspace, or the collection's in an existing one, and requests inherit it. An operation with its own security gets its own authentication, and one with an empty security list gets No Auth. When an operation accepts several alternatives, Relay uses the first one it supports. When an operation needs an API key together with another scheme, the key becomes a header or query parameter on the request.

For OpenID Connect, fill in the authorization and token URLs from the provider's discovery document. For more about the types, see Inheriting authentication.

Warnings

The Preview lists anything Relay couldn't import exactly as the spec describes it, such as a missing server, path parameters without values, security schemes it doesn't support, operations whose method it can't send, webhooks, and external examples, which it doesn't download.

See Also