Zyvra

API Specs

An API spec is a file that describes an API: its endpoints, parameters and responses. Zyvra reads OpenAPI 3 files, YAML or JSON. Keep one with your project, read it, edit it, and see whether the responses you get match it.

Add a spec

Open API Specs in the sidebar and choose Add a spec:

  1. Choose the file, or paste its text.
  2. Give it a name (letters, digits, - and _).

Zyvra saves the document as specs/<name>.yaml (or .json) in your project folder, so it goes to Git with the rest, and adds a line to zyvra.yaml:

specs:
  - name: shop
    file: specs/shop.yaml

You can also write that by hand. The file must be inside the project folder, no larger than 5 MB, and .yaml, .yml or .json. Swagger 2 files are not supported: convert them to OpenAPI 3 first.

Read an operation

A spec is shown as a table of its operations: method, path, summary and the response codes it declares. Click a row to open it in a panel: its description, parameters (path, query, header), request body and every response, each with its schema (fields, types, which are required, allowed values, nested objects) and an example, plus the security it needs.

Open it in the API Client, save it, or mock it

Every operation row has an actions menu (the three dots) with Open in API Client and Create mock (the operation panel has the same menu).

  • Open in API Client asks where to send it: type an address, or pick the spec’s own server or a mock service of the project. The Open in API Client button in the dialog gives you the request ready to send. Or save it as a request in a collection (an existing one, or A new collection…); it goes in a folder named after the operation’s tag.
  • Create mock adds the operation to a mock service as an endpoint: choose a service, or A new mock service… with a name and port. If the service already has that method and path, nothing changes and you are told.

Add a collection to a spec

In the API Client, open the menu of a collection, a folder or a single request and choose Add to API Spec. Pick a spec, or A new spec…, and every request in it becomes an operation: its address, query and header parameters, path parameters (:id becomes {id}) and an example JSON body. The response is a placeholder (200) for you to fill in on the Edit tab. Operations the spec already has are not changed; they are listed after, with any request that could not be added. A new spec takes its server from the collection’s base address.

Add a mock service to a spec

On Mock Services, open a service’s menu and choose Add to API Spec. Each endpoint becomes an operation, and the responses are what its scenarios answer: the status of each and its body as the example. Disabled endpoints, and scenarios that run a script, are left out and listed. A new spec takes the mock’s address as its server. Operations the spec already has are not changed. To add just one endpoint, use Add to API Spec in that endpoint’s menu on the service page.

Edit a spec

The Edit tab opens the spec file in a code editor, with the problems marked as you type. A syntax error is underlined on its line; each problem the OpenAPI validation finds is listed (click one to jump to it); and the operations you have added or removed since the last save are shown. Text that is not a usable OpenAPI 3 document cannot be saved, warnings can. Revert goes back to the saved file. If you leave with unsaved changes, Zyvra asks first.

This also lets you repair a spec that Zyvra cannot read.

Check that a response matches the spec

In the API Client, every response says whether it matches the spec that describes its request: “Matches the spec shop GET /products”, or “Differs from the spec”, with what is wrong, naming the field ([0].price: value must be a number).

It checks that the status is one the operation declares, that the content type is one it lists, and that a JSON body fits the schema. That works for a mock and for a real service alike. A response is only checked when a spec describes its request, and nothing is shown otherwise.

The request is matched to an operation by method and path. Parameter names do not matter: /orders/{id}, /orders/{orderId} and /orders/:id are the same endpoint. A base path in the spec’s servers (for example https://api.example.com/v1) is understood, and a path with fixed words (/products/featured) wins over one with a parameter (/products/{id}).

Replace or remove a spec

On a spec’s page you can Replace file with a newer version, Download it, or remove it. Removing keeps the file on disk unless you choose Remove and delete the file.

Not here yet

Importing a spec from an address, and checking a request’s body and parameters against the spec, are not built yet. To create mock endpoints from a spec, use Import OpenAPI on a mock service (see Importing).