Accessing and updating an imported API's documentation

When you import a specification, Restorm does not only create requests: it keeps the API’s documentation — descriptions, models, security schemes, examples, enumerations — and attaches it to the environment folder the import created.

Reaching the documentation

The environment folder’s Docs tab

This is the main view. Open the environment folder the import produced: its sub-tab bar carries a Docs tab, next to Environments, Custom variables and Notes.

The tab only appears if the folder came from an import — an environment folder you created by hand has no documentation to show.

The other entry points

From	What you get
A request’s Docs tab	The documentation for that one operation — with no table of contents and no general information block. It only appears if the operation is found in the specification
A plain folder’s Docs tab	The documentation restricted to the operations that folder holds
The environment folder’s home sub-tab	The View documentation card — “Browse the API documentation, models and endpoints”
The welcome screen (API card)	The Documentation quick link
The title bar’s search engine	A documentation preview when you hover a result

What the view contains

From top to bottom:

• the API’s title and its description;
• an information block: Version, Source format (with a link to the source URL), Server (schemes, host, base path), Contact, License, Terms of service, External docs;
• one section per tag, with its description;
• one block per operation: method and URL, summary, group badge, a deprecated badge where applicable, a Security section (scheme type, OAuth 2 flows, scopes), and a collapsible Example payload;
• the Parameters and Responses tables (status codes are colour-coded);
• Models — an interactive graph of the schemas, navigable and zoomable;
• Polymorphism — the oneOf / anyOf / allOf compositions;
• Enums — the enumerations, merged with the folder’s own.

Note

These section headings (Models, Enums, Parameters, Responses, Security, Example payload) are displayed in English in every language of the application. They are reproduced as they are here so that you recognise them on screen.

Creating a request from the documentation

Every operation block carries a + Add button that creates a request pre-configured for that operation. That is the shortest route when an import was partial, or when an operation has just appeared in the specification.

Navigating and searching

A table of contents is anchored on the right — Overview, Operations, Models, Enums sections — collapsible and resizable. Clicking a model scrolls to the graph and centres the matching node in it.

Shortcut	Effect
Ctrl+F / Cmd+F	Opens search within the documentation
F3 / Enter	Next match
Shift+F3 / Shift+Enter	Previous match
Esc	Closes the search

A counter shows your position within the results.

Updating the documentation

A specification changes. Restorm can go and fetch the source again and apply the delta — documentation and requests — without overwriting your work.

URL imports only

Re-syncing is only available if the folder was imported from a URL. An import from a file or by pasting records no source, and the refresh button does not appear: the home sub-tab then shows “This folder was not created from an importable source.”

That URL cannot be changed afterwards in the interface. To change source, import again.

Where the button is

Two entry points, equivalent to one another:

1. the environment folder’s home sub-tab, Spec updates section — it shows the URL, the Last import and the Last check, and carries the Refresh button;
2. right-clicking the folder in the sidebar tree → Refresh.

There is no automatic checking

Restorm does not watch your specifications in the background and will not warn you that a new version is available. The check is always triggered by you.

What happens

1. A “Refreshing spec…” window appears while the source is fetched. The URL’s and the headers’ {{variables}} are resolved, and the attached authentication route is played first.
2. Restorm compares a fingerprint of the fetched source with the one recorded at the last import.
3. Nothing has changed → “The API spec is up to date.”, and that is that.
4. Something has changed (or the fetch failed) → the re-sync wizard opens.

The wizard

• The source URL is shown read-only.
• A pill lets you attach, change or detach an authentication route, and a Custom headers submenu lets you add fixed headers replayed on every refresh.
• Two preview tabs:
  • Routes — the tree of operations found in the new version, with a filter and a selection. Operations already present in your folder are locked and always ticked; you only choose which of the new ones to add;
  • Documentation — the new version’s documentation, read-only, before you confirm.
• The confirm button shows the number of new operations selected, for example Apply update (3).

Note

The wizard is currently displayed in English whatever the application’s language (“Refresh from source”, “Apply update”, the “Routes” and “Documentation” tabs). The English wording is therefore reproduced here as it is.

What is changed, and what is not

This is the important point: the specification has authority over what it describes, you have authority over the rest.

Element	Behaviour
A request’s name	Never changed
Method and URL	Never changed
Existing parameters, headers and path parameters	Kept as they are — value, description, enabled state
Parameters added by the specification	Added, with the specification’s default value or empty
Parameters removed from the specification	Kept on the request
A new operation	Added where a fresh import would have placed it (tag folder included)
An operation marked deprecated by the specification	Flagged; it appears dimmed in the tree
An operation that has vanished from the specification	Flagged as removed; it appears struck through in the tree, remains runnable and is never deleted
API documentation and enumerations	Replaced entirely by the new version — that is what refreshes the Docs tab

Nothing is ever deleted from your tree: an operation that disappears from the source is marked, not erased.

If the source requires authentication

A 401 or 403 response opens the wizard with the error message shown as it is (for example HTTP 401: Unauthorized). Attach an authentication route or add fixed headers, and the preview is run again.

Re-syncable formats

Twelve formats have re-syncing: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC and Smithy.

For all the others, a new import creates a new tree. The complete list is in Updating from the source.