Import an OpenAPI spec

Import an OpenAPI 3.x document to get one request per API operation, grouped by tag. Each request is ready to send once you fill in the values.

Before you start

• OpenAPI 3.x in JSON only. YAML files and Swagger 2.0 specs aren't supported. Convert them to OpenAPI 3 JSON first.
• The file must be .json and no larger than 10 MB.

Import the spec

The steps are the same as for a Postman file:

1. In the EXPLORER header, click More actions → Import collection.
2. Click Select File and choose your spec. Collapy recognises it by the "openapi": "3.x" field.
3. Review the preview and any Warnings.
4. Choose a Destination: New collection (named after the spec's info.title), Workspace root, or Existing collection.
5. Leave Import N variable(s) as environment ticked to create an environment named <API title> Variables with your base URL. You almost always want this.
6. Click Import, then Close when you see the summary.

See Import a Postman collection for details about the preview, destinations and the summary screen.

How the spec maps to Collapy

In the spec	In Collapy
info.title, info.description	Name and description of the new collection
tags	One sub-collection per tag, in the order the spec declares them. An operation with several tags goes into its first tag's collection, with a warning. Untagged operations go directly into the destination.
Each path + method	One request. Its name is the operation's summary, or METHOD /path if there's no summary.
servers[0].url	Every request URL starts with {{baseUrl}}. The environment gets a baseUrl variable with the server URL. If the spec lists no servers, baseUrl is empty.
Server variables, such as {region}	Extra environment variables with their default values. The defaults are also filled into baseUrl.
Path templates like /users/{id}	Path variables: /users/:id. See Path variables.
query parameters	Query params
path parameters	Path variable values
header parameters	Headers
Parameter example / examples	The parameter's value
requestBody with application/json (or *+json)	A Raw (JSON/Text) body

Parameters

• Required parameters are imported enabled, and their description starts with (required).
• Optional parameters are imported disabled, so the request doesn't send placeholder values. Enable the ones you need.

Request bodies

Collapy uses the first of these that exists:

1. the media type's example
2. the first entry in examples
3. an example generated from the schema, the way Swagger UI does it: strings become "string" (or a sample date, email, URL or UUID, depending on format), numbers become 0, booleans become false, and arrays get one item. $refs to components/schemas, allOf, oneOf and anyOf are followed.

Replace the generated values with real data before you send.

Authentication

Collapy uses the first scheme in the spec's top-level security and puts it on the new collection. Credentials are left blank, so fill them in afterwards.

Security scheme	Collapy auth
http with bearer	Bearer Token
http with basic	Basic Auth
apiKey in a header or query	API Key with the key name filled in
oauth2, openIdConnect, cookie apiKey, other http schemes	Skipped with a warning

Operation-level security overrides are ignored, with a warning. Every request uses the collection's auth.

Check tag collections' auth

Sub-collections created from tags are set to No Auth, and that stops inheritance. To make requests use the auth on the top-level collection, open each tag collection and set its Auth to Inherit Auth from Parent.

What isn't imported

• YAML and Swagger 2.0 files
• Responses and response schemas
• Request bodies that aren't JSON, such as XML, form data or multipart. These are skipped with a warning.
• Cookie parameters
• OAuth 2.0 and OpenID Connect auth
• Callbacks and webhooks
• $refs that point to other files

Keep a workspace in sync

On the Ultra plan, a synced workspace re-imports from an OpenAPI URL whenever you click Sync now or your CI calls the workspace's webhook URL, instead of being imported once. See Plans and limits.

FAQ

I have a YAML spec. What can I do?

Convert it to JSON with any YAML-to-JSON tool or your API framework's export, then import the JSON file.

Why are some query parameters greyed out?

They're optional in the spec, so Collapy imports them disabled. Tick them to include them in the request.

Related

• Import a Postman collection
• Collections and the Explorer
• Variables
• Path variables
• Authentication
• Plans and limits