Specs

The Specs section is an editor for OpenAPI 3 and Swagger 2.0 documents, in YAML or JSON. It checks the spec as you type against a set of lint rules, generates a collection from it, and keeps that collection in step when the spec changes, without losing the tests and scripts you’ve added. You can also go the other way and build a spec from an existing collection.

123456

A spec linked to its collection, with live lint results.

1. Save the spec as YAML or JSON
2. Generate a linked collection, or sync the linked one
3. Replace the spec with one generated from a collection
4. Open HTML docs for the spec in your browser
5. The linked collection; Unlink is on the right
6. Lint problems with severity, rule and location

×

Create a spec

1. Click Specs in the API client’s left rail, then + at the top of the sidebar.

   A spec named New API opens with a short OpenAPI 3.0.3 example: one server, https://api.example.com, and a GET /items operation.

2. Click the name and type a new one.

3. Replace or edit the text. Paste an existing spec here, or write a new one.

   The Problems list updates a moment after you stop typing.

You can also bring in a spec file:

• Import in the Collections section (Import and export) adds an OpenAPI or Swagger file as a new collection and as a spec in this section. The two aren’t linked, so Sync Collection isn’t available for that collection.
• cloakctl spec import adds the spec and a collection that is linked to it. See From the command line.

The spec editor

Control	What it does
Spec name	The name in the sidebar, and the file name in the workspace.
YAML / JSON	Whether the spec is saved as a .yaml or .json file. It doesn’t convert the text; the spec is read as JSON when it starts with { and as YAML otherwise.
Generate Collection	Shown when no collection is linked. Creates a collection from the spec, links it and opens it.
Sync Collection	Shown when a collection is linked. Updates that collection from the spec. See Sync a collection with its spec.
From Collection	Lists your collections. Choosing one replaces the spec’s text with an OpenAPI document generated from that collection.
Preview Docs	Builds HTML API documentation from the spec and opens it in your browser.
Linked to	The linked collection (click to open it), and the result of the last sync, such as 2 added, 1 updated.
Unlink	Removes the link. The collection stays; Sync Collection becomes Generate Collection again.
Editor	The spec’s text.
Problems	The lint results: the number of problems, Looks good when there are none, and the number of errors (high-severity problems) when there are any.

Each problem shows a severity badge (High, Medium or Low), a message, and the rule name with a JSON pointer to the place in the spec, such as operation-tags · /paths/~1pets/get. In a pointer, ~1 stands for / and ~0 for ~. Problems are sorted with the most severe first.

To delete a spec, right-click it in the sidebar and choose Delete. Deleting a spec doesn’t delete its collection.

Lint rules

Lint runs governance-style checks like the ones Postman applies to specs, plus structural checks. High problems are errors: cloakctl spec lint exits with 1 when there’s at least one.

Document and info

Rule	Severity	Reported when
syntax	High	The text isn’t valid JSON or YAML. No other rules run.
openapi-version	High	There’s no openapi (or swagger) version field. No other rules run.
info	High	There’s no info object.
info-title	High	info.title is missing or empty.
info-version	High	info.version is missing.
info-description	Low	info.description is missing or empty.
info-contact	Low	info.contact is missing, so consumers can’t tell who owns the API.

Servers (OpenAPI 3 only)

Rule	Severity	Reported when
servers	Medium	No servers are defined.
servers-https	Medium	A server URL starts with http:// and isn’t a localhost URL.

Paths

Rule	Severity	Reported when
paths	High	There’s no paths object. No path or operation rules run.
path-format	High	A path doesn’t start with /.
path-trailing-slash	Low	A path (other than /) ends with /.
path-casing	Low	A path without {parameters} has uppercase letters. Most APIs use lowercase kebab-case.

Operations

These run for each get, put, post, delete, options, head, patch and trace operation.

Rule	Severity	Reported when
operation-summary	Medium	The operation has no summary.
operation-description	Low	The operation has no description.
operation-id	Medium	The operation has no operationId. It’s needed for SDK generation.
operation-id-unique	High	Two operations use the same operationId.
operation-tags	Low	The operation has no tags.
path-params	High	The path uses {name} but no path parameter called name is declared (on the operation or the path), or a declared path parameter isn’t in the path.
parameter-description	Low	A parameter declared on the operation has no description.
security	Medium	The spec has no top-level security, and the operation doesn’t declare security either. Add security: [] to mark an operation as public. Not checked for options and head.
request-body	Low	A post, put or patch operation has no requestBody (OpenAPI 3 only).

Responses and components

Rule	Severity	Reported when
responses	High	The operation has no responses.
success-response	Medium	None of the responses is a 2xx or 3xx.
response-schema	Medium	A 2xx response (other than 204) has no schema.
unused-component	Low	A schema under components/schemas is never referenced with #/components/schemas/Name.

Tip

Fix High problems first: they usually mean the generated collection, docs or SDK will be wrong. Low problems are about documentation quality.

Generate a collection from a spec

Click Generate Collection. Cloak Proxy creates a collection, links it to the spec, opens it and shows a message such as Generated “Petstore” with 3 requests. The same conversion is used when you import an OpenAPI or Swagger file.

From the spec	Becomes
info.title	The collection name (Imported API when there’s no title).
info.description	The collection’s docs.
The first server (or Swagger schemes, host and basePath)	The collection variable baseUrl, with server variables replaced by their defaults and any trailing slash removed. http://localhost when there’s no server.
Security schemes	Collection auth, using the scheme named in the top-level security (or the first one): API key → API Key with {{apiKey}}; HTTP basic → Basic Auth with {{username}} and {{password}}; other HTTP schemes → Bearer Token with {{bearerToken}}; OAuth 2 → OAuth 2.0 with {{accessToken}}, {{clientId}} and {{clientSecret}}, and the grant type, auth URL and token URL from its client credentials, authorization code (as PKCE) or password flow.
Tags	Folders, in the order the spec declares them. Each operation goes in the folder of its first tag; untagged operations go at the top level.
Each operation	A request named after its summary, else its operationId, else METHOD /path, with the URL {{baseUrl}}/path. Deprecated operations start their docs with Deprecated.
Path parameters	:name path variables, with example values.
Query and header parameters	Query params and headers with example values. Required ones are turned on; optional ones are added but turned off.
Request body	A JSON body from the example or schema, form fields for form and multipart bodies, or raw text or XML.
Responses	Saved examples, one per status code (default becomes 200), named after the response description, with an example body built from the schema. These are what a mock server serves.

Example values come from the spec’s example, examples, default or first enum value. Without one, Cloak Proxy fills in a typed placeholder: 0 for numbers, true for booleans, "string", or a sample in the right format for dates, emails, UUIDs and URLs.

Sync a collection with its spec

When the spec changes, click Sync Collection to bring the linked collection up to date. Sync updates what comes from the spec and keeps what you added.

Requests are matched by method and path. Path parameters are compared by position, so :petId, {{petId}} and {petId} count as the same segment.

Case	What happens
An operation matches a request	The request takes the spec’s method, URL, parameters, path variables and headers. Values and on/off states you set are kept, and parameters you added yourself stay. The body is replaced only if yours is empty. The docs are replaced when the spec has a description. Examples from the spec that you don’t have (by name) are added. Scripts, tests, auth, settings and your examples are kept.
A folder matches a tag by name	The folder keeps its scripts, auth and docs.
A new operation	A new request is added in its tag’s folder.
An operation was removed from the spec	Its request moves to a folder named Removed from spec, instead of being deleted. Delete those requests when you no longer need them.
A request you made by hand	Requests whose URL doesn’t start with a variable from the spec, such as {{baseUrl}}, are yours: they stay where they are.
Collection docs and variables	Your collection docs are kept (the spec’s description is used only if you have none). Variables from the spec that the collection lacks are added.

The result shows next to Linked to: for example 1 added, 2 updated, 1 moved to “Removed from spec”, 4 unchanged, or Already in sync (8 requests) when nothing changed.

Commit before a big sync

Sync edits the collection in place. If the workspace is in Git, commit first so you can review the changes in the Git view and undo them if needed.

Create a spec from a collection

Use From Collection in the spec editor, or Export › OpenAPI 3.0 (YAML)… on a collection, to describe an existing collection as OpenAPI 3.0.3. This works well for collections built from captured traffic.

Caution

From Collection replaces all of the spec’s current text. Create a new spec first if you want to keep the old one.

From the collection	Becomes
Collection name and docs	info.title and info.description. info.version is 1.0.0.
baseUrl variable, and hosts of absolute request URLs	servers.
Each HTTP and GraphQL request	An operation at its path, without the leading {{variable}} or host. :id becomes {id}.
Request name	summary, and a camelCase operationId (List pets → listPets).
First folder	The operation’s tag.
Request docs	description.
Path variables, query params and headers	Parameters. Query params are required when they’re turned on. Content-Type, Accept, Authorization and Cookie headers are left out.
Raw JSON body	requestBody with a schema inferred from the JSON and the body as the example.
Saved examples	Responses by status code, with inferred schemas and the example bodies. A request without examples gets a 200 OK response.

Inferred schemas detect integer, number, boolean, string, array and object, and the date-time, uuid and email formats.

Preview docs

Preview Docs turns the spec into a temporary collection and opens its HTML documentation in your browser, with a navigation sidebar, every operation, its parameters and body, code samples and example responses. It’s a quick way to read the spec the way your API’s users will. To export docs you can publish, see Generate docs, SDKs and MCP servers.

From the command line

cloakctl spec lints, imports and syncs specs without the app.

Terminal

# Lint a spec; exit code 1 if there's any High problem
cloakctl spec lint openapi.yaml

# Add a spec to the workspace with a linked collection
cloakctl spec import openapi.yaml

# Update the workspace spec from a file, then sync its collection
cloakctl spec sync openapi.yaml

Command	What it does
spec lint FILE	Prints one line per problem (severity, rule, message, pointer), then N problems (N errors) or No problems found. Exits with 1 when there’s a High problem. Use it as a CI gate.
spec import FILE	Adds the spec to the workspace, named after its title, and creates its linked collection.
spec sync FILE	Finds the workspace spec named after the file’s info.title (or the name you give with --spec NAME), replaces its text with the file, and syncs the linked collection. Prints the summary, then each added (+), updated (~) and removed (-) request.
spec sync SPEC_NAME	Syncs a workspace spec’s linked collection with its current text.
--workspace DIR	Use a different workspace folder (all spec commands except lint).

spec sync fails with a message if the spec isn’t in the workspace yet (import it first) or isn’t linked to a collection.

Output of cloakctl spec lint

MEDIUM security  GET /pets doesn't declare security (or document that it's public with security: [])  /paths/~1pets/get
LOW    operation-tags  GET /pets has no tags  /paths/~1pets/get

2 problems (0 errors)

AI assistants connected to the Cloak Proxy MCP server can use list_specs, get_spec, save_spec, lint_spec, sync_spec and generate_openapi.

Where specs are stored

Each spec is saved as its own .yaml or .json file in the workspace’s specs folder, next to a small .meta.json file that records its name, format and linked collection. The spec file holds exactly the text you wrote, so it diffs cleanly in Git and can be used by other tools.

• DirectoryWorkspace/

  • Directorycollections/

    • …
  • Directoryspecs/

    • Petstore.yaml
    • Petstore.meta.json

Related

Import and exportBring in OpenAPI files and export collections.

Mock serversServe the examples a spec generates.

Generate docs, SDKs and MCP serversPublish what you've specified.

Turn traffic into API docsFrom captured requests to a spec.