> For the complete documentation index, see [llms.txt](https://techwritingtools.gitbook.io/dockit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://techwritingtools.gitbook.io/dockit/documentation/dockit-user-guide.md).

# DocKit User Guide

**User Guide for version 0.3.x**

[DocKit](https://marketplace.visualstudio.com/items?itemName=DocKit.oas-docs) is a Visual Studio Code (VS Code) extension for reviewing and editing OpenAPI specifications. DocKit helps technical writers review and improve the quality of API documentation in OpenAPI specification files. It adds OpenAPI-aware navigation, editing, validation, spelling and terminology checks, optional prose style checks, and other documentation tools to VS Code.

This guide is for technical writers who edit an existing OpenAPI specification. It assumes that you understand the technical concepts behind REST APIs and OpenAPI, but it does not assume that you are an API developer.

{% hint style="info" %}
DocKit works with OpenAPI 3.1.x, OpenAPI 3.0.x, and OpenAPI 2.0 (Swagger 2.0) specifications. In this guide, **OpenAPI specification** refers to the specification document you are editing.
{% endhint %}

## Before you start

### Requirements

You need:

* Visual Studio Code **1.118.0 or later**.
* An OpenAPI 3.1.x, OpenAPI 3.0.x, or OpenAPI 2.0 (Swagger 2.0) specification in one of these formats:
  * `.json`
  * `.jsonc`
  * `.yaml`
  * `.yml`

DocKit does not require a separate runtime. Its validation, linting, spelling, terminology, and style checks run locally.

### What DocKit adds to VS Code

DocKit provides two VS Code view containers:

* **DocKit** — the primary sidebar. It contains **Search**, **OpenAPI Outline**, and **References**.
* **DocKit: Inspector** — the secondary sidebar. It contains **All Issues** and **Summary**.

<figure><img src="/files/h7ITwTPuqN7RjGTOQTpk" alt=""><figcaption></figcaption></figure>

Together, these views let you move between the structure of an OpenAPI specification, the source document, and the quality issues detected in that document.

DocKit activates automatically when you open a `.json`, `.jsonc`, `.yaml`, or `.yml` file. Its OpenAPI features engage when the document has a top-level `openapi` or `swagger` property.

## Install DocKit

<figure><img src="/files/sZKEL8Db3KrgbIhvNbbY" alt=""><figcaption></figcaption></figure>

### Install from the VS Code Marketplace

{% stepper %}
{% step %}
Open Visual Studio Code
{% endstep %}

{% step %}
Open the **Extensions** view
{% endstep %}

{% step %}
Search for **DocKit** or `dockit.oas-docs`
{% endstep %}

{% step %}
Select **DocKit: OpenAPI Documentation Toolkit**
{% endstep %}

{% step %}
Select **Install**
{% endstep %}
{% endstepper %}

You can also install the extension from the command line:

```bash
code --install-extension dockit.oas-docs
```

### Install from the command line

If Visual Studio Code is already installed and its `code` command is available in your terminal, run:

```bash
code --install-extension dockit.oas-docs
```

After installation, open an OpenAPI specification file to activate DocKit.

## Set up the DocKit layout

<figure><img src="/files/0U3tjcb9p3XeMVONJlA2" alt=""><figcaption></figcaption></figure>

DocKit is designed to work with the VS Code editor between two sidebars:

<table><thead><tr><th>Primary sidebar (DocKit)</th><th>Code editor (OpenAPI specification)</th><th>Secondary sidebar (DocKit: Inspector)</th></tr></thead><tbody><tr><td>Search</td><td></td><td>Summary</td></tr><tr><td>OpenAPI Outline</td><td><pre class="language-json"><code class="lang-json">paths:
  /pets:
    get:
      summary: ...
</code></pre></td><td>All Issues</td></tr><tr><td>References</td><td></td><td></td></tr></tbody></table>

The first time you use DocKit, VS Code may place **DocKit: Inspector** in the primary sidebar. Move it to the secondary sidebar once; VS Code remembers the layout.

### Move the DocKit Inspector to the secondary sidebar

{% stepper %}
{% step %}
Open the **DocKit** view from the Activity Bar
{% endstep %}

{% step %}
Locate the **DocKit: Inspector** view container
{% endstep %}

{% step %}
Show the secondary sidebar if needed

If the secondary sidebar is hidden, open the Command Palette (`Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS) and run **View: Toggle Secondary Side Bar**.
{% endstep %}

{% step %}
Drag the **DocKit: Inspector** view container to the secondary sidebar
{% endstep %}
{% endstepper %}

Once the layout is in place, open your OpenAPI specification in the editor. The **OpenAPI Outline** populates from the document structure, and the **DocKit:Inspector** becomes available for the selected node and document diagnostics.

{% hint style="info" %}
You can drag the DocKit: Inspector to another VS Code view location if that works better for your workspace. The two-sidebar layout is recommended because it lets you keep the specification, navigation, and diagnostics visible at the same time.
{% endhint %}

## A recommended documentation workflow

DocKit is most useful when you use it as part of a review workflow rather than as a collection of independent commands.

For a technical writer reviewing an existing specification, a practical sequence is:

{% stepper %}
{% step %}
Open the specification
{% endstep %}

{% step %}
Inspect the OpenAPI Outline

Understand the document structure and locate the areas you need to review.
{% endstep %}

{% step %}
Run validation, spelling/terminology checks, and any linting rules

Run the checks that your project uses.
{% endstep %}

{% step %}
Resolve structural and quality issues

Resolve these issues before editing prose.
{% endstep %}

{% step %}
Edit documentation fields

Edit summaries, descriptions, tags, servers, and other scalar values with Leaf Editing where appropriate.
{% endstep %}

{% step %}
Generate code snippets

Generate snippets when you need to inspect or provide an example request.
{% endstep %}

{% step %}
Trace `$ref` dependencies

Trace dependencies when you need to understand how a component is used.
{% endstep %}

{% step %}
Export a public specification

Export a copy with internal endpoints removed when needed.
{% endstep %}

{% step %}
Review the exported specification before publishing it
{% endstep %}
{% endstepper %}

The order matters. Technical writers often need developers or product managers to clarify technical behavior before they can make a documentation change. DocKit can help you find and describe the problem; it does not replace the subject-matter information you need to resolve it.

## Navigate an OpenAPI specification

### OpenAPI Outline

<figure><img src="/files/GtpHieYlp2pGpnG6MLZd" alt=""><figcaption></figcaption></figure>

The **OpenAPI Outline** is the main navigation view for an OpenAPI specification. It presents the document as an OpenAPI-aware tree instead of requiring you to navigate a large JSON or YAML file manually.

The outline can include:

* Root metadata such as the title, version, and servers.
* Paths and HTTP operations.
* Parameters and responses.
* Request and response schemas.
* Components and definitions.
* Security schemes and other reusable objects.

### Navigate from the Outline to the editor

Select a node in the Outline to move the editor to the corresponding location in the specification.

This is useful when you need to inspect the surrounding source or make a structural change that Leaf Editing does not support.

### Follow the editor cursor

The **Follow Cursor** option keeps the Outline synchronized with the node at the current cursor position in the editor.

To enable it:

{% stepper %}
{% step %}
Open the **...** menu in the OpenAPI Outline
{% endstep %}

{% step %}
Select **Follow Cursor**
{% endstep %}
{% endstepper %}

The corresponding setting is `dockit.followCursor`, which is `false` by default.

### Filter the Outline

Use **Filter on Type** to filter the Outline as you type.

To enable or disable it:

{% stepper %}
{% step %}
Open the **...** menu in the OpenAPI Outline
{% endstep %}

{% step %}
Select **Filter on Type**
{% endstep %}
{% endstepper %}

The corresponding setting is `dockit.filterOnType`, which is `true` by default.

### Change the sort order

The Outline supports these sort orders:

* **Position** — document order. This is the default.
* **Name** — alphabetical order.
* **Category** — groups nodes by node type.

Use **Sort By** in the Outline's **...** menu.

### Group endpoints by tag

Use **Group by Tag** to organize endpoints under their global tags. The selected sort order still applies within each group.

This view can be useful when the API is organized around functional areas and you want to review one tag at a time.

The corresponding setting is `dockit.outlineGroupBy`, which is `"none"` by default.

## Review the specification with DocKit: Inspector

<figure><img src="/files/Wo1PaSmbwNDnWoBkIzmI" alt=""><figcaption></figcaption></figure>

The **DocKit: Inspector** provides contextual information and diagnostics for the selected node and the open specification.

It contains two views:

* **All Issues**
* **Summary**

### All Issues

The All Issues view brings together the quality checks that DocKit performs.

Findings are grouped into:

1. **Validation** — structural or schema-compliance problems.
2. **Linting** — selected Spectral and DocKit governance rules.
3. **Spelling** — spelling and terminology findings.
4. **Styles** — optional prose style findings.

Select an issue to move the editor to the relevant location.

You can change the grouping from the view's menu.

#### Understand the four diagnostic categories

<table><thead><tr><th width="152.4000244140625">Check</th><th>What it tells you</th></tr></thead><tbody><tr><td><strong>Validation</strong></td><td>Whether the specification conforms to the applicable OpenAPI schema and parser rules.</td></tr><tr><td><strong>Linting</strong></td><td>Whether the specification follows the API rules you have chosen to enforce.</td></tr><tr><td><strong>Spelling</strong></td><td>Whether documentation text contains words or terminology that the checker does not recognize.</td></tr><tr><td><strong>Styles</strong></td><td>Whether documentation prose triggers an enabled style rule.</td></tr></tbody></table>

A finding is not necessarily a defect in the same sense across all four categories. Validation problems can make a specification structurally invalid. Linting and style findings are policy or guidance checks that you can choose to apply. Spelling findings can require editorial judgment, particularly for product names and technical terminology.

### Summary

The Summary view describes the selected node and, for objects, can show the distribution of property types in a donut chart. It also provides property and child counts and reference information where applicable.

Use Summary when you want a quick structural view of the selected element rather than its raw JSON or YAML representation.

## Edit documentation fields

### Leaf node editing

**Leaf node editing** lets you change scalar values directly from the OpenAPI Outline. It is intended for values such as:

* `summary`
* `description`
* `tags`
* `servers`
* scalar configuration values
* enum values
* Boolean values such as `deprecated`

To edit a value:

{% stepper %}
{% step %}
Find the node in the **OpenAPI Outline**
{% endstep %}

{% step %}
Hover over the scalar value
{% endstep %}

{% step %}
Select the **Edit** pencil icon
{% endstep %}

{% step %}
Enter the new value or select a value from the available options
{% endstep %}

{% step %}
Press **Enter** to apply the change
{% endstep %}
{% endstepper %}

The change is made in the source document and can be undone with the normal VS Code undo command (`Ctrl+Z` or `Cmd+Z`).

### What leaf node editing does not do

Leaf node editing is for scalar values: strings, numbers, and boolean values.

Use the main editor for structural changes such as:

* adding a new path or operation
* creating a new object
* adding or removing schema properties
* deleting an entire object or block

Leaf node editing is therefore a focused documentation-editing aid, not a replacement for the OpenAPI source editor.

## Search a large specification

The **Search** view provides a dedicated search experience for large OpenAPI specifications.

To search:

{% stepper %}
{% step %}
Open **DocKit → Search**
{% endstep %}

{% step %}
Enter a search term
{% endstep %}

{% step %}
Review the matching keys, paths, and scalar values
{% endstep %}

{% step %}
Select a result to move the editor to the matching location
{% endstep %}
{% endstepper %}

Search results update as you type. For example, you can search for an operation ID, schema name, security scheme, or documentation term.

You can also use the search panel for free-text lookup. From the Outline, `Ctrl+Alt+F` (`Cmd+Alt+F` on macOS) can be used to open the relevant search workflow.

## Trace `$ref` dependencies

The **References** view helps you understand relationships between reusable components.

To inspect references:

{% stepper %}
{% step %}
Select a schema or other reusable component

Select it in the editor or OpenAPI Outline.
{% endstep %}

{% step %}
Open **DocKit → References**
{% endstep %}

{% step %}
Review the two dependency lists

* **Incoming References** — elements that reference the selected component.
* **Outgoing References** — components referenced by the selected component.
  {% endstep %}

{% step %}
Select a reference to navigate to its location
{% endstep %}
{% endstepper %}

This is particularly useful when a developer asks you to change a shared schema or when you need to determine where a component is used before changing its documentation.

{% hint style="info" %}
References help you understand dependencies; they do not tell you whether a proposed API change is technically or semantically correct. Confirm those changes with the appropriate API owner or developer.
{% endhint %}

## Validate the specification

DocKit performs version-aware validation for supported OpenAPI specifications.

### Editor schema validation

For JSON specifications, DocKit supplies version-aware schemas for:

* OpenAPI 3.1.0--3.1.2
* OpenAPI 3.0.0--3.0.4
* OpenAPI 2.0 (Swagger 2.0)

This prevents a valid document from being incorrectly checked against a schema for a different OpenAPI version. The version-aware schema also supports editor validation and autocomplete.

### DocKit structural validation

DocKit also performs structural validation through its OpenAPI parser. This validation works with both JSON and YAML.

Validation findings appear:

* inline in the editor,
* in the VS Code **Problems** panel, and
* under **Validation** in the Inspector's **All Issues** view.

Validation runs as you work, with changes processed after a short delay, and can also run when you save the file. The `dockit.validateOnSave` setting controls validation on save and is enabled by default.

### Run validation manually

{% stepper %}
{% step %}
Open the Command Palette

Use `Ctrl+Shift+P` or `Cmd+Shift+P`.
{% endstep %}

{% step %}
Run **DocKit: Validate OpenAPI Document**
{% endstep %}

{% step %}
Review the findings

Review findings in **Problems** or **DocKit: Inspector → All Issues**.
{% endstep %}
{% endstepper %}

Resolve structural problems before spending time on detailed prose edits when possible. A structurally incorrect document can make other findings harder to interpret.

## Lint the API

API linting checks the specification against rules you choose to enable.

DocKit uses the built-in `spectral:oas` rules together with 19 DocKit governance rules (`dockit-*`). Linting is **off by default**.

This makes linting different from validation:

* **Validation** checks whether the document is structurally valid.
* **Linting** checks whether it follows selected API design and governance recommendations.

### Enable linting

<figure><img src="/files/gK74bWY6BZbTxIQf6rhU" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}
Open VS Code Settings

Use `Ctrl+,` or `Cmd+,`.
{% endstep %}

{% step %}
Enable `dockit.linting.enabled`
{% endstep %}

{% step %}
Add the rules you want to `dockit.linting.enabledRules`
{% endstep %}
{% endstepper %}

The `enabledRules` setting is an allowlist. It is empty by default. Turning on the master setting without selecting any rules does not produce linting findings.

The Settings editor provides a list of available rules and descriptions.

### Choose rules deliberately

DocKit's 19 custom `dockit-*` rules cover areas such as:

* URL and REST conventions
* security
* naming
* developer experience
* lifecycle metadata

Examples include:

* `dockit-paths-kebab-case`
* `dockit-no-crud-verbs-in-paths`
* `dockit-path-contains-version`
* `dockit-schema-names-pascal-case`
* `dockit-property-camel-case`
* `dockit-require-servers-https`
* `dockit-no-http-basic-auth`
* `dockit-define-error-response-400`
* `dockit-require-rate-limit-headers`
* `dockit-deprecated-operation-has-description`

These rules represent API governance recommendations. They are optional because API teams can have different requirements.

### View the complete rules catalog

Run **DocKit: Open Rules Reference** from the Command Palette to open a browsable catalog of the available linting rules and styles, including their descriptions and current enabled or disabled status.

Linting findings appear in the **Problems** panel and under **Linting** in **All Issues**.

## Check spelling and terminology

DocKit checks spelling and terminology in documentation-oriented fields instead of treating every string in the specification as ordinary prose.

The checker focuses on human-facing content such as:

* `description`
* `summary`
* tag descriptions

It avoids treating keys, path templates, and `$ref` values as ordinary prose.

Spelling and terminology checks are always enabled. There is no separate master setting.

### Review and fix findings

Spelling findings appear:

* under **Spelling** in the Inspector's **All Issues** view,
* in the VS Code **Problems** panel, and
* as editor diagnostics where applicable.

When a replacement is available, use the VS Code lightbulb (`Ctrl+.` or `Cmd+.`) to apply the suggested fix.

### Why technical terminology can still be flagged

The bundled dictionary includes everyday English, software terms, REST/OpenAPI terminology, and other technical vocabulary. It cannot contain every product name, company name, internal term, or specialized domain term.

When DocKit flags a legitimate term, add it to a custom dictionary rather than repeatedly ignoring the same finding.

## Apply prose style checks

DocKit can check `description` and `summary` prose against optional rule sets adapted from these Vale styles:

* Google
* Microsoft
* IBM
* write-good
* alex

Each style is disabled by default. You can enable any combination of styles independently.

Examples of issues that these checks can identify include:

* passive voice
* wordiness
* weasel words
* clichés
* terminology or inclusive-language concerns

### Enable a style

<figure><img src="/files/ZVdJbN4GyIs2Je6eUquZ" alt=""><figcaption></figcaption></figure>

Open VS Code Settings (`Ctrl+,` or `Cmd+,`) and search for `dockit.spellCheck.styles`.

Enable the style or styles you want.

There is no master switch for style checks. Each style is controlled independently.

Style findings appear:

* in the VS Code **Problems** panel, and
* under **Styles** in the Inspector's **All Issues** view.

Some findings include a quick fix when the rule provides a replacement.

{% hint style="info" %}
A style finding is a recommendation, not necessarily a defect. Review the suggested change in context before applying it. Technical documentation sometimes needs terminology, constructions, or passive voice that a general style rule does not understand.
{% endhint %}

## Use custom dictionaries

Custom dictionaries help you keep legitimate product names and domain terms from being reported as spelling errors.

DocKit supports two ways to add words:

1. an inline list in `dockit.spellCheck.words`
2. external dictionary files in `dockit.spellCheck.customDictionaries`

### Add inline words

In VS Code Settings, add the words to `dockit.spellCheck.words`.

For example:

```json
"dockit.spellCheck.words": [
  "GraphQL",
  "OAuth2",
  "Kubernetes",
  "AcmeCorp"
]
```

Inline words come directly from your settings and are applied even when the workspace is not trusted.

### Add an external dictionary

Set `dockit.spellCheck.customDictionaries` to the paths of your dictionary files.

For example:

```json
"dockit.spellCheck.customDictionaries": [
  ".vscode/company-terms.txt"
]
```

DocKit reads up to two external dictionary files. The files must resolve to locations inside the current workspace.

Supported file types include `.txt`, `.json`, and `.dic`. The documented text and JSON formats are:

**`.txt`**

Use one word per line. Blank lines and lines beginning with `#` or `//` are ignored.

```
# Product and domain terms
Acmecorp
WidgetFlow
Kubernetes
idempotency
```

**`.json`**

Use a flat array of strings:

```json
["Acmecorp", "WidgetFlow", "Kubernetes", "idempotency"]
```

Use individual words rather than phrases.

### External dictionary security

DocKit treats external dictionary files as untrusted input.

* **Workspace Trust is required.** DocKit does not read external dictionary files in an untrusted (Restricted Mode) workspace.
* **Workspace containment is required.** The resolved file must be inside a current workspace folder. Paths that escape the workspace through `..` or symlinks are rejected.
* **File limits apply.** DocKit reads at most two files, each no larger than 5 MB, with no more than 100,000 custom words in total.
* **Word-length limits apply.** Words longer than 80 characters are skipped.
* Entries are sanitized before DocKit adds them to the dictionary.

A dictionary entry must be a single token that starts with an ASCII letter and contains only letters, digits, and the supported identifier characters. Multi-word phrases and entries containing unsupported characters are ignored.

## Export a public specification

When an OpenAPI specification contains internal operations that should not appear in public documentation, use **Export Public Spec** to create a separate copy.

The command is:

**`DocKit: Export Public Spec (Remove Internal Endpoints)`**

The source specification is not modified.

### Mark internal operations

DocKit identifies internal operations or paths by a configurable vendor extension. The default key is:

```yaml
x-internal: true
```

The setting `dockit.publicExport.internalExtension` controls the key. The default is `x-internal`.

### Export the specification

{% stepper %}
{% step %}
Open the master OpenAPI specification
{% endstep %}

{% step %}
Open the Command Palette

Use `Ctrl+Shift+P` or `Cmd+Shift+P`.
{% endstep %}

{% step %}
Run **DocKit: Export Public Spec (Remove Internal Endpoints)**
{% endstep %}

{% step %}
Choose the output path when prompted
{% endstep %}
{% endstepper %}

By default, the output uses the source format and a `.public` name, such as:

* `api.public.json`
* `api.public.yaml`

During export, DocKit:

1. removes operations or whole paths marked with the internal extension;
2. removes the internal marker from surviving public operations when `dockit.publicExport.stripInternalMarker` is enabled; and
3. optionally prunes components that DocKit can prove are unreachable.

### Optional component pruning

Component pruning is disabled by default.

Enable `dockit.publicExport.pruneUnusedComponents` if you want DocKit to remove components that become unreachable after internal operations are removed.

The pruning process uses transitive `$ref` and name-based reference analysis. Components marked `x-keep: true` are retained.

### Review the exported specification

{% hint style="warning" %}
**Always review the exported specification before publishing it.**
{% endhint %}

Export Public Spec automates the removal of elements according to the rules and settings you configure. It does not determine whether the resulting specification is complete, technically correct, or suitable for publication.

Review at least:

* the remaining paths and operations;
* servers and URLs;
* schemas and examples;
* security requirements;
* references;
* documentation descriptions and summaries; and
* any organization-specific publication requirements.

Keep the original master specification as the source of truth.

## Generate code snippets

DocKit can generate request snippets for operations in **OpenAPI 3.x** specifications. Supported output:

* **cURL**&#x20;
* **Python (`requests`)**&#x20;

The generated request includes information available from the operation definition, such as the URL, headers, and request body.

To generate a snippet:

{% stepper %}
{% step %}
Open an OpenAPI 3.x specification
{% endstep %}

{% step %}
Open the Command Palette

Use `Ctrl+Shift+P` or `Cmd+Shift+P`.
{% endstep %}

{% step %}
Run **DocKit: Generate Code Snippets**
{% endstep %}

{% step %}
Select the operation
{% endstep %}

{% step %}
Review or copy the generated request snippet
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Code snippet generation supports OpenAPI 3.x. It does not support OpenAPI 2.0 (Swagger 2.0).&#x20;
{% endhint %}

Use generated snippets as examples of the request represented by the specification. Review the generated code before publishing it as documentation.

## Convert between JSON and YAML

DocKit can convert an active OpenAPI specification between JSON and YAML.

To convert a specification:

{% stepper %}
{% step %}
Open the source `.json` or `.yaml` file
{% endstep %}

{% step %}
Open the Command Palette

Use `Ctrl+Shift+P` or `Cmd+Shift+P`.
{% endstep %}

{% step %}
Run **DocKit: Convert OAS (JSON ↔ YAML)**
{% endstep %}

{% step %}
Review the converted document in the new editor tab
{% endstep %}
{% endstepper %}

The source file is not modified.

## Configure DocKit

Open VS Code Settings with `Ctrl+,` (`Cmd+,` on macOS) and search for `dockit`.

### General settings

<table><thead><tr><th width="264.199951171875">Setting</th><th width="128.60009765625">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>dockit.validateOnSave</code></td><td><code>true</code></td><td>Validate the specification when the file is saved.</td></tr><tr><td><code>dockit.showValuePreviews</code></td><td><code>true</code></td><td>Show scalar value previews next to nodes in the Outline.</td></tr><tr><td><code>dockit.followCursor</code></td><td><code>false</code></td><td>Keep the Outline synchronized with the editor cursor.</td></tr><tr><td><code>dockit.filterOnType</code></td><td><code>true</code></td><td>Filter the OpenAPI Outline as you type.</td></tr><tr><td><code>dockit.outlineSortOrder</code></td><td><code>"position"</code></td><td>Sort the Outline by <code>"position"</code>, <code>"name"</code>, or <code>"category"</code>.</td></tr><tr><td><code>dockit.outlineGroupBy</code></td><td><code>"none"</code></td><td>Group endpoints by tag with <code>"tag"</code>, or show the normal tree with <code>"none"</code>.</td></tr></tbody></table>

### Linting settings

<table><thead><tr><th width="265">Setting</th><th width="134.39990234375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>dockit.linting.enabled</code></td><td><code>false</code></td><td>Enable the linting engine.</td></tr><tr><td><code>dockit.linting.enabledRules</code></td><td><code>[]</code></td><td>Allowlist of linting rule IDs to run. An empty list means no linting findings.</td></tr></tbody></table>

### Prose style settings

<table><thead><tr><th width="333">Setting</th><th width="96.5999755859375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>dockit.spellCheck.styles.google</code></td><td><code>false</code></td><td>Enable Google developer documentation style checks.</td></tr><tr><td><code>dockit.spellCheck.styles.microsoft</code></td><td><code>false</code></td><td>Enable Microsoft Writing Style checks.</td></tr><tr><td><code>dockit.spellCheck.styles.ibm</code></td><td><code>false</code></td><td>Enable IBM style checks.</td></tr><tr><td><code>dockit.spellCheck.styles.writeGood</code></td><td><code>false</code></td><td>Enable write-good readability checks.</td></tr><tr><td><code>dockit.spellCheck.styles.alex</code></td><td><code>false</code></td><td>Enable alex inclusive-language checks.</td></tr></tbody></table>

### Dictionary settings

<table><thead><tr><th width="333">Setting</th><th width="96.199951171875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>dockit.spellCheck.words</code></td><td><code>[]</code></td><td>Inline list of words that the spell checker always accepts.</td></tr><tr><td><code>dockit.spellCheck.customDictionaries</code></td><td><code>[]</code></td><td>Paths to external custom dictionary files. DocKit reads up to two eligible files inside the current workspace.</td></tr></tbody></table>

### Public export settings

<table><thead><tr><th width="380.2000732421875">Setting</th><th width="131">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>dockit.publicExport.internalExtension</code></td><td><code>"x-internal"</code></td><td>Vendor extension used to identify internal operations or paths.</td></tr><tr><td><code>dockit.publicExport.stripInternalMarker</code></td><td><code>true</code></td><td>Remove the internal marker from surviving operations in the exported specification.</td></tr><tr><td><code>dockit.publicExport.pruneUnusedComponents</code></td><td><code>false</code></td><td>Remove components proven unreachable after internal content is removed. Components marked <code>x-keep: true</code> are retained.</td></tr></tbody></table>

### Command reference

All commands are available from the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`).

<table><thead><tr><th width="335.60009765625">Command</th><th>Purpose</th></tr></thead><tbody><tr><td><strong>DocKit: Validate OpenAPI Document</strong></td><td>Validate the active specification.</td></tr><tr><td><strong>DocKit: Lint OAS File</strong></td><td>Run the linting rules you have enabled.</td></tr><tr><td><strong>DocKit: Open Rules Reference</strong></td><td>Open the catalog of available linting rules and styles.</td></tr><tr><td><strong>DocKit: Check Spelling</strong></td><td>Run spelling and terminology checks.</td></tr><tr><td><strong>DocKit: Export Public Spec (Remove Internal Endpoints)</strong></td><td>Create a copy with internal endpoints removed.</td></tr><tr><td><strong>DocKit: Convert OAS (JSON ↔ YAML)</strong></td><td>Convert the active specification between JSON and YAML.</td></tr><tr><td><strong>DocKit: Generate Code Snippets</strong></td><td>Generate cURL and Python (<code>requests</code>) snippets for an OpenAPI 3.x operation.</td></tr><tr><td><strong>DocKit: Show DocKit</strong></td><td>Reveal the DocKit sidebar.</td></tr><tr><td><strong>DocKit: Show DocKit Inspector</strong></td><td>Reveal the DocKit: Inspector sidebar.</td></tr><tr><td><strong>DocKit: Follow Cursor</strong></td><td>Toggle cursor synchronization with the Outline.</td></tr><tr><td><strong>DocKit: Filter on Type</strong></td><td>Toggle Outline filtering while typing.</td></tr><tr><td><strong>DocKit: Sort By: ...</strong></td><td>Choose the Outline sort order.</td></tr><tr><td><strong>DocKit: Group by Tag</strong></td><td>Toggle grouping of endpoints by tag.</td></tr></tbody></table>

## Troubleshoot common problems

### The DocKit: Inspector view is in the wrong sidebar

Move the **DocKit: Inspector** view container to the secondary sidebar.

If the secondary sidebar is hidden, run **View: Toggle Secondary Side Bar** from the Command Palette.

### Linting findings do not appear

Check both settings:

1. `dockit.linting.enabled` must be `true`.
2. `dockit.linting.enabledRules` must contain at least one rule ID.

The rule list is empty by default, so enabling the master switch alone does not produce findings.

### Style findings do not appear

Check the individual style settings under `dockit.spellCheck.styles.*`.

All styles are disabled by default.

### A legitimate technical term is reported as misspelled

Add the term to `dockit.spellCheck.words` or to an eligible external dictionary.

### An external dictionary does not load

Check that:

* the workspace is trusted;
* the file is inside the current workspace after path resolution;
* the file uses a supported extension;
* no more than two dictionary files are configured;
* each file is no larger than 5 MB; and
* the entries meet the dictionary limits and sanitization rules.

### A settings change does not appear to affect the open specification

DocKit responds to settings changes and reruns the relevant checks. If the results do not update as expected, switch to the specification tab or run the applicable command manually, such as **DocKit: Lint OAS File** or **DocKit: Check Spelling**.

## Privacy and offline operation

* DocKit performs its core processing locally:
  * DocKit does not collect telemetry.
  * Validation, parsing, linting, and spell checking do not make external network calls.
  * The processing engines run locally in the VS Code extension host or lint worker.

This allows you to use DocKit's core documentation-quality checks without sending the specification to an external service.

## Known limitations

* Very large specifications (5 MB or more) can take a few seconds to build the initial Outline and complete the lint pass. Linting runs in a background worker so that the editor remains responsive.
* Code snippet generation supports OpenAPI 3.x only.

## Support and feedback

For documentation and product feedback:

* **User Guide:** <https://techwritingtools.gitbook.io/dockit/documentation>
* **GitHub repository:** <https://github.com/techwritetools/dockit-oasdocs>
* **Issue tracker:** <https://github.com/techwritetools/dockit-oasdocs/issues/new>
* **Marketplace extension ID:** `dockit.oas-docs`

If you find a bug or have an idea for improving DocKit, use the issue tracker so that the request can be tracked with the project.

## What changed in version 0.3.x&#x20;

Version 0.3.1 adds or changes several capabilities that are particularly relevant to technical writers:

* API linting is now configurable and opt-in.
* 19 DocKit governance rules were added.
* The **Open Rules Reference** catalog provides a browsable list of linting rules and styles.
* Optional Vale-based prose style checks were added for Google, Microsoft, IBM, write-good, and alex styles.
* Custom inline and external spell-check dictionaries were added.
* **Export Public Spec** removes internal operations without modifying the source specification.
* Optional conservative component pruning was added to public export.
* The Outline can group endpoints by tag.
* Active Outline options are indicated in the ***...*** menu.
* The bundled dictionary was rebuilt to reduce false positives from obscure words.
* Spelling and Style findings are now separate groups in **All Issues**.
* JSON editor schema validation is version-aware for Swagger 2.0, OpenAPI 3.0.x, and OpenAPI 3.1.x.
* Several spelling, path-rendering, and style-checking false positives were corrected.
* Style suggestions appear in the Problems panel and can provide quick fixes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://techwritingtools.gitbook.io/dockit/documentation/dockit-user-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.