Importing an OpenAPI or Swagger spec

Turn an OpenAPI 3.x document into ready-to-send requests and response schemas in SchemaClient — and validate the live API against the contract it published.

Updated

If your API already has an OpenAPI document, you have written the contract once — there is no reason to retype it as requests and schemas. Importing the spec gives you both in a few seconds, and turns the spec from documentation into something you can actually test against.

Import the document

  1. Open SchemaClient and choose Import.
  2. Pick your OpenAPI 3.x file — JSON or YAML both work.
  3. SchemaClient reads the operations and creates a request for each: method, path, and the parameters the spec declares.

The response definitions in the spec are extracted as schemas at the same time, so each imported request comes with the shape its response is supposed to have.

Send the generated requests

The imported requests behave like any request you built by hand — set the base URL for the environment you are hitting, add auth if the API needs it, and send. If you are new to the request workflow, testing a REST API covers it end to end.

Validate the API against its own contract

This is the step that pays for the import. A spec that lives next to the code drifts: fields get added without being documented, types change, nullability changes. Validate the live response against the schema that came from the spec and the drift stops being invisible:

  • Response matches the spec — the contract holds; consumers reading your docs get what the docs promise.
  • Response fails validation — either the implementation or the spec is wrong. Fixing whichever one is lying is cheaper now than after a consumer builds against it.

The mechanics of validation — required fields, types, nullability — are the same as for hand-written schemas, covered in validating API responses.

No spec? Generate schemas from traffic instead

If the API you are testing has no OpenAPI document (most internal and third-party APIs do not), SchemaClient can infer a schema from responses it has already seen — capture the traffic with the monitor, generate a schema from a real response, and tighten it by hand. You end up with a contract even for APIs that never published one.

Frequently asked questions

Which OpenAPI versions does SchemaClient support?

OpenAPI 3.x documents, in JSON or YAML. Older Swagger 2.0 files should be converted to OpenAPI 3 first — most spec tools, including swagger.io's editor, do this conversion in one step.

What does SchemaClient generate from the spec?

Two things: requests for the operations the spec defines (method, path, parameters), and schemas extracted from the spec's response definitions, which you can then validate real responses against.

Can I check that my API actually matches its OpenAPI spec?

Yes — that is the main reason to import one. Send the generated requests at your running API and validate each response against the schema extracted from the spec. Where they disagree, either the API or the documentation is wrong, and both are worth knowing.