Guides

Importing your spec

Bring an existing OpenAPI / Swagger / cURL collection into a workspace.

Updated

You usually don’t start from scratch. OpenAPI Studio imports from every common source.

Supported sources

SourceFormatNotes
OpenAPI 3.0 / 3.1JSON or YAMLNative; round-trips cleanly.
Swagger 2.0JSON or YAMLAuto-converted to OpenAPI 3.0 on import.
URLhttps://…Spec is fetched server-side.
File upload.json / .yaml / .ymlUp to 10 MB.
Raw pasteEither formatUseful when copying from chat / docs.
cURL commandtextGenerates a single endpoint with parameters and body inferred.

How to import

From the workspace, click New spec → Import. Pick a source above. The importer:

  1. Parses and validates the document.
  2. Converts Swagger 2.0 if needed.
  3. Pre-processes references and resolves obvious issues.
  4. Surfaces validation problems as a list — fix them inline or Import anyway and address later.
  5. Drops you into the flow builder with the spec loaded.

cURL → endpoint

Paste a command like:

curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer abc" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada", "role": "admin"}'

The importer creates:

  • A POST /v1/users operation (path under your default server).
  • Parameters for any query strings.
  • Headers as parameters (with Authorization mapped to a bearer security scheme on the spec).
  • A request body with the JSON payload as both schema and example.

You can keep adding cURL commands and the importer extends the same spec — useful for capturing real-world traffic into a new spec.

Validation on import

The importer runs the same validation as the editor:

  • Structural OpenAPI conformance.
  • Resolvable $refs.
  • Unique operationIds where present.
  • WebSocket extensions if any (URL must resolve, message templates well-formed).

Errors block the import; warnings let you proceed.

Updating an existing spec

To replace the contents of an existing spec, open it and use Spec → Replace from import. Rather than wiping everything, the merger:

  • Adds new paths.
  • Updates changed paths (showing a diff before commit).
  • Highlights paths that exist locally but not in the import (you decide whether to keep or drop).