API specifications explain how an API behaves and how it interacts with other APIs.
API specs can function like API documentation, but they also explain the values, parameters, and objects in the schema of the API. An API spec helps users know how to make requests to the APIs contained within the spec.
Insomnia parses the following from your API specs and displays these in the sidebar of the API spec in the Insomnia UI:
|
API spec definition |
Object in Insomnia |
|---|---|
description
|
Displays in the Docs tab of a request. |
| info | Displays in the left-sidebar of the spec under INFO. |
servers.url
|
Displays in the left-sidebar of the spec under SERVERS. |
paths
|
Displays in the left-sidebar of the spec under PATHS. |
requestBodies
|
Displays in the left-sidebar of the spec under REQUEST BODIES. |
schemas
|
Displays in the left-sidebar of the spec under SCHEMAS. |
securitySchemes
|
Authentication information and options. Displays in the left-sidebar of the spec under SECURITY. |
responses
|
List of structured, expected responses for each request. Displays in the left-sidebar of the spec under RESPONSES. |
parameters
|
List of parameters that the API recognizes. Displays in the left-sidebar of the spec under PARAMETERS. |
The following sections provide common API spec use cases you can solve with Insomnia.
|
Use case |
Instructions |
|---|---|
| Create a new spec directly in the Insomnia editor |
In your Insomnia workspace, click Create and select Design document. Your spec editor is in the center pane.
For more information, see Create a design document. |
| Import an existing spec |
In your workspace, click Import and select the source of the import: File, URL, or Clipboard.
For more information, see Import an API specification as a design document in Insomnia. |
|
Use case |
Instructions |
|---|---|
| Automatic linting on your specs (new or imported) directly in Insomnia | Navigate to the design document with your API spec. The linting error messages display below the center pane. |
| Automate linting on specs using the Inso CLI |
Run inso lint spec and select the spec from the list that displays.
For more information, see the inso lint spec reference.
|
| Use custom linting to ensure your spec adheres to your team or company’s standards |
To lint locally, create a .spectral.yaml file with the custom rules in the same directory as the oas.yaml file you want to lint. Then run inso lint spec ./oas.yaml from that directory. To apply custom lint rules in the Insomnia UI, add the .spectral.yaml file to the root of the collection git repository at the same level as the .insomnia folder.
|
|
Use case |
Instructions |
|---|---|
| Automatically generate a collection and requests from your spec |
From your design document with your API spec, click the Settings icon and select Generate collection.
For more information, see Generate a collection from a design document. |
| Use mock servers to mock your requests |
Run a request, then click the Mock tab in the response pane. Create a new mock server there along with the route for the request.
For more information, see Mock server. |
|
Use case |
Instructions |
|---|---|
| Collaborate with a team on API specs using Git sync and version control |
You can collaborate on API specs by cloning your existing repository with the specs.
For more information, see how to Git sync in Insomnia. |
What API spec formats are supported in Insomnia?
Specs must be in the OpenAPI 2.0.x or later format. You can create specs for a REST API or GraphQL API.
Why is a preview not displaying for my spec?
Check to make sure your spec is in the OpenAPI 2.0.x or later format. Next, check for any errors in the linting and resolve those.
Why can’t I generate a collection from the API spec in my design document?
Check the linting errors, if there’s any warning level errors, you won’t be able to generate a collection from your spec.
How do I migrate my specs from another API client, like Postman, to Insomnia?
You can import any of your specs from another API client to Insomnia. Just import the file in your Insomnia workspace.
Can I create a GraphQL API spec in Insomnia?
Yes. For Insomnia to autodetect that your spec is in GraphQL format, the path must be /graphql, the method must be POST, the request body must be application/json and must contain a property query with the type string, and the response body must be application/json.
Can I create a spec in a collection?
No, you can import an existing spec into a collection, but you can only create a new API spec in a document.