{"id":32122433,"url":"https://github.com/speclynx/vscode-openapi-toolkit","last_synced_at":"2025-10-20T20:47:48.143Z","repository":{"id":305157306,"uuid":"1022078356","full_name":"speclynx/vscode-openapi-toolkit","owner":"speclynx","description":"The OpenAPI Powerhouse for VSCode","archived":false,"fork":false,"pushed_at":"2025-09-28T21:14:49.000Z","size":42,"stargazers_count":7,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-28T23:21:52.666Z","etag":null,"topics":["extension","extension-vscode","openapi2","openapi3","openapi31","vscode"],"latest_commit_sha":null,"homepage":"https://speclynx.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/speclynx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-18T12:17:22.000Z","updated_at":"2025-09-18T11:05:34.000Z","dependencies_parsed_at":"2025-07-18T17:30:37.844Z","dependency_job_id":"862980f7-c664-4954-a541-7c552b61115d","html_url":"https://github.com/speclynx/vscode-openapi-toolkit","commit_stats":null,"previous_names":["speclynx/vscode-openapi-toolkit"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/speclynx/vscode-openapi-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speclynx%2Fvscode-openapi-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speclynx%2Fvscode-openapi-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speclynx%2Fvscode-openapi-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speclynx%2Fvscode-openapi-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speclynx","download_url":"https://codeload.github.com/speclynx/vscode-openapi-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speclynx%2Fvscode-openapi-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280158801,"owners_count":26282553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-20T02:00:06.978Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extension","extension-vscode","openapi2","openapi3","openapi31","vscode"],"created_at":"2025-10-20T20:47:45.881Z","updated_at":"2025-10-20T20:47:48.137Z","avatar_url":"https://github.com/speclynx.png","language":null,"readme":"\u003cdiv\u003e\n  \u003ca href=\"https://speclynx.com\"\u003e\u003cimg width=\"739\" height=\"103\" alt=\"image\" src=\"https://github.com/user-attachments/assets/87c88ea9-5746-497a-8c33-43fa55b72b0b\" /\u003e\u003c/a\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003cp\u003e\n    Stop wrestling with OpenAPI specs — SpecLynx OpenAPI Toolkit delivers the most effective way to author and manage your API specs, bringing unprecedented ease, pinpoint accuracy, and unmatched power directly to your VSCode workflow.  \n  \u003c/p\u003e\n\u003c/div\u003e  \n\n\u003cbr\u003e\n\n[![SpecLynx OpenAPI Toolkit](https://speclynx.com/assets/images/speclynx-openapi-toolkit.png)](https://speclynx.com)\n\n## Why Choose SpecLynx OpenAPI Toolkit?\n\nSpecLynx OpenAPI Toolkit is engineered for clarity, control, and confidence, enabling you to focus on designing exceptional APIs.\n\n### OpenAPI Authoring\n\nGet full YAML/JSON autocompletion, inline documentation hints, validation, linting, and live preview as you type — so you catch errors before they cost you time. OpenAPI Toolkit surfaces context-aware suggestions for paths, parameters, responses, components, ...; flags missing or mismatched fields instantly; and renders a side-by-side spec-to-UI preview that updates with every keystroke. Say goodbye to manual spec checks and hello to a fluid authoring experience that keeps your API specs accurate and up-to-date.\n\n### One-Click Tooling\n\n- Powered by a powerful [Language Server](https://microsoft.github.io/language-server-protocol/)\n- JSON Schema Validation\n- Semantic Validation \u0026 Linting\n- Spectral Validation \u0026 Linting\n- OpenAPI Description dereferencing\n- Workspace-Wide Operations\n\nAll these commands — and more — are just a keystroke away in VS Code, so you can focus on designing great APIs instead of wrestling with tooling.\n\n### Built by Veterans\n\nSpecLynx OpenAPI Toolkit is crafted by industry veterans, [Vladimír Gorej](https://vladimirgorej.com) and [Francesco Tumanischvili](https://github.com/frantuma), who bring over **15 years of dedicated experience maintaining and evolving Swagger/OpenAPI tools**. Their unparalleled expertise ensures you receive a solution with battle-tested reliability and best practices meticulously baked into every feature.\n\n## What is it?\n\nOpenAPI Toolkit provides advanced editing, processing, rendering, and execution capabilities for Swagger/OpenAPI files (2.0, 3.0, 3.1). These include an editor experience — offering validation/linting, completion, documentation, syntax highlighting, reference navigation, and more — along with a preview panel (based on Swagger UI) for rendering the OpenAPI document and allowing interaction and execution.\n\nSeveral capabilities are unique in the VS Code OpenAPI ecosystem, such as Spectral support in the web, custom semantic linting, in-context documentation (including in completion items), full JSON/YAML parity, and rich reference handling.\n\nWe are actively expanding the feature set and fixing bugs; this documentation will be updated accordingly.\u0026#x20;\n\n## Capabilities\n\n### Editor\n\n#### Foreword\n\n**JSON and YAML** — OpenAPI Toolkit provides the same level of support for OpenAPI specs written in JSON or YAML format. It also aims to provide editor capabilities even for not-well-formed documents (for example, offering completion and syntax highlighting where possible).\n\nOpenAPI Toolkit supports following OpenAPI versions with a consistent feature set:\n\n- [OpenAPI 2.0 (Swagger)](https://spec.openapis.org/oas/v2.0.html)\n- [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4.html)\n- [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.1.html)\n\n###### OpenAPI 2.0 (Swagger)\n\n![OpenAPI (Swagger) 2.0 support](https://github.com/user-attachments/assets/c1d7d002-97e8-48cc-a64d-30e4c8987655)\n\n###### OpenAPI 3.0.x\n\n![OpenAPI 3.0.x support](https://github.com/user-attachments/assets/cfcc92af-648b-41d4-bddf-e74fdd493645)\n\n###### OpenAPI 3.1.x\n\n![OpenAPI 3.1.x support](https://github.com/user-attachments/assets/0e0e7017-e4f9-40e7-b7ad-303b8934d582)\n\n**Web support** — OpenAPI Toolkit is designed to run both on Desktop and in Web environments such as [vscode.dev](https://vscode.dev/), [github.dev](https://github.dev/), and [GitHub Codespaces](https://github.com/features/codespaces). It is one of the few extensions that deliver advanced OpenAPI editing and validation/linting in the web environment.\u0026#x20;\n\n#### In-context OpenAPI Documentation (hover)\n\nWhen you hover over a keyword (node key) in the document, the extension shows full, context-aware documentation in a hover panel that corresponds to the selected construct and matches the official specification.\n\n![In-context OpenAPI Documentation ](https://github.com/user-attachments/assets/7aaf568d-9a2f-4d4f-bb63-9d38db654579)\n\nThe same documentation is also shown in the details pane of completion items. See the “Completion / Suggestions” section below.\u0026#x20;\n\n#### Completion / Suggestions\n\nOpenAPI Toolkit provides an enriched completion experience. Under the hood, completion is driven by a semantic understanding of the node where completion is triggered, making suggestions far more precise and useful than standard JSON-Schema-based completion.\u0026#x20;\n\n##### Completion documentation\n\nEach completion item includes full documentation (the same content shown in hover).\n**Tip:** If the documentation panel doesn’t appear to the right of the completion label, click the `\u003e` icon that appears when you hover the completion entry.\u0026#x20;\n\n![Completion documentation](https://github.com/user-attachments/assets/1d90a38b-427a-4b23-a8f8-aeaa1aa2d448)\n\n##### References completion\n\nWhen completion is triggered within the value of a `$ref` field, the editor offers suggestions of compatible targets found in the document (this will be expanded to include documents across the workspace). It also displays the referenced content in the completion box, providing an in-context view of potential references without losing focus\u0026#x20;\n\n![References completion](https://github.com/user-attachments/assets/d293593c-332a-4183-abca-5cbf944176cb)\n\n##### Context-aware completion (e.g., `type: integer` → `format`)\n\nSuggestions adapt to related fields. For example, if a schema sets `type: integer`, the `format` suggestions include only compatible values.\u0026#x20;\n\n![Context-aware completion](https://github.com/user-attachments/assets/6ef34a33-f7b4-4341-9edb-e8641e626914)\n\n#### References\n\n##### Reference target content in hover\n\nHovering over the value of a `$ref` field displays the referenced content in the hover box, providing an in-context view of references without losing focus.\u0026#x20;\n\n![Preview reference target](https://github.com/user-attachments/assets/4882f6e3-7b13-4cd7-84ab-8ce2e3a4081c)\n\n\n##### Go to definition (F3)\n\nRight-click the value of a `$ref` field and choose **Go to Definition** (or press **F3**) to jump to the reference target—either within the current file or in another file in the workspace.\u0026#x20;\n\n![Go to definition](https://github.com/user-attachments/assets/a5c1610a-1c06-4c8d-8316-46f953755cd8)\n\n##### Go to references\n\nRight-click a key (for example, under `components.schemas`) and choose **Go to References** to open a panel listing available references to jump to.\u0026#x20;\n\n![Go to references](https://github.com/user-attachments/assets/2cb17ad2-cd43-4945-94a7-746c6397a82a)\n\n##### Find all references\n\nRight-click a key (for example, of a schema) and choose **Find All References** to open the References panel listing every usage of the selected target.\u0026#x20;\n\n![Find all references](https://github.com/user-attachments/assets/9b00b3b1-03f3-4252-b7b9-4a853f00783d)\n\n##### Dereference command\n\nRight-click inside an OpenAPI document or right-click the file in the Explorer, then choose **OpenAPI Toolkit → Dereference API Document** to save a dereferenced copy locally. The default output name is `{filename}-dereferenced.{extension}`.\u0026#x20;\n\n![Dereference command](https://github.com/user-attachments/assets/e7bc9c2b-95be-4508-8212-1f2dd99334c3)\n\n#### Syntax Highlighting\n\nOpenAPI Toolkit provides **semantic** syntax highlighting, going beyond basic keyword coloring. Specific OpenAPI elements—such as operations, schemas, and reference objects—are highlighted with distinct colors and font styles. This helps you quickly recognize and distinguish different parts of an API definition, improving readability and navigation in complex specifications.\u0026#x20;\n\n![Semantic Syntax Highlighting](https://github.com/user-attachments/assets/b67c64b5-771d-4eb1-81d3-359872e7607b)\n\n#### Validation and Linting\n\n##### Definitions\n\n* **Validation** — Checks that the document conforms to the OpenAPI and JSON Schema specifications.\n* **Linting** — Analyzes an OpenAPI document against a configurable ruleset. Unlike validation (which only checks spec conformance), linting enforces best practices, style guidelines, and quality standards. It can catch issues such as inconsistent naming, missing descriptions, or patterns that harm API usability—even when the document is technically valid.\n* **Semantic validation** — Validates using rules that target semantic properties of elements (e.g., `operation`, `schema`) rather than only applying JSON Schema. This enables more precise checks and clearer diagnostics (including highlighting the exact key, value, or child node that’s wrong).\n* **Semantic linting** — Lints using rules that can target semantic element types and/or JSONPath expressions. Compared to tools that only support JSONPath, this hybrid approach simplifies writing targeted rules (including for nested elements) and yields more precise editor markings.\u0026#x20;\n\n##### Validation/Linting modes\n\nOpenAPI Toolkit supports three modes, which you can combine:\n\n1. **JSON Schema validation** — Standard validation based on OpenAPI JSON Schemas\n2. **Spectral validation and linting**\n3. **Semantic validation and linting**\u0026#x20;\n\n![Validation/Linting modes](https://github.com/user-attachments/assets/36d55b1d-6cfa-41db-8656-1242e3e946c0)\n\n##### Default configuration\n\nBy default, JSON Schema validation and **semantic linting** are enabled. You can change this in the extension settings. **Semantic validation** is currently disabled by default because it has not yet completed a full compliance test cycle; once complete, it is expected to become the default validation method.\u0026#x20;\n\n##### Spectral validation/linting\n\nTo enable Spectral-based checks:\n\n1. Enable **Apply Spectral Validation** in the extension settings.\n2. Provide a ruleset by either:\n   **(a)** adding a `.spectral.json`, `.spectral.yaml`, or `.spectral.yml` at the root of your workspace, **or**\n   **(b)** setting the Spectral ruleset file path in the extension settings, or via the command **OpenAPI Toolkit: Pick Spectral Validation/Linting Rules File** (available from the editor context menu or the Explorer).\n\nRefer to the [Spectral documentation](https://docs.stoplight.io/docs/spectral/) for ruleset format details.\u0026#x20;\n\n###### Create a Spectral ruleset\n![Create a Spectral ruleset](https://github.com/user-attachments/assets/1cb7691d-7fba-4b82-96b8-3a0344aa2ba4)\n\n###### Use a Spectral ruleset\n![Use a Spectral ruleset](https://github.com/user-attachments/assets/2bfd9175-a42b-43e2-96ad-1217b60bebcd)\n\n##### Semantic validation\n\nEnable **Apply Semantic Validation** in the extension settings. No rules file is required to run the built-in semantic validation checks.\u0026#x20;\n\n![Semantic Validation](https://github.com/user-attachments/assets/6245a7f4-71d2-46f9-a271-b031728ace4c)\n\n##### Semantic linting\n\nTo run semantic linting:\n\n1. Enable **Apply Semantic Linting** in the extension settings.\n2. Provide a ruleset by either:\n   **(a)** adding a rules file at the workspace root named `.speclynx.json`, `.speclynx.yaml`, `.speclynx.yml` (or without the leading dot), **or**\n   **(b)** setting the semantic ruleset file path in the extension settings, or via the command **OpenAPI Toolkit: Pick Semantic Validation/Linting Rules File** (available from the editor context menu or the Explorer).\u0026#x20;\n\n##### Semantic linting rules (overview)\n\nSemantic lint rules are defined in JSON or YAML. A ruleset typically includes:\n\n* **Rule ID** and **description/message**\n* **Severity** (e.g., error, warning, info)\n* **Target selector**: a semantic **element type** (e.g., `operation`, `schema`, `parameter`, etc.) and/or a **JSONPath** for precise targeting\n* **Condition(s)** to evaluate (e.g., required fields, naming patterns, min/max constraints)\n* **Optional fixes** or suggestions (when applicable)\n\n![Semantic linting rules](https://github.com/user-attachments/assets/a2f3e0d8-8178-43a6-b26c-f1678b3a7622)\n\nA separate section provides the complete rule schema and examples. *(If you don’t see it yet, it will be added as the rules stabilize.)*\u0026#x20;\n\n##### Supported major element “types” for semantic checks\n\nThese are the current high-level element types recognized by the semantic engine.\n\n| \u0026nbsp;            | \u0026nbsp;                  | \u0026nbsp;                   |\n|-------------------|-------------------------|--------------------------|\n| `callback`        | `components`            | `contact`                |\n| `content`         | `definitions`           | `discriminator`          |\n| `encoding`        | `example`               | `external-documentation` |\n| `header`          | `headers`               | `info`                   |\n| `items`           | `license`               | `link`                   |\n| `media-type`      | `oauth-flow`            | `oauth-flows`            |\n| `openapi`         | `openapi3_0`            | `openapi3_1`             |\n| `operation`       | `parameter`             | `parameters-definitions` |\n| `path-item`       | `paths`                 | `path-template`          |\n| `reference`       | `request-body`          | `response`               |\n| `responses`       | `responses-definitions` | `schema`                 |\n| `scopes`          | `security-definitions`  | `security-requirement`   |\n| `security-scheme` | `server`                | `server-variable`        |\n| `swagger`         | `tag`                   | `xml`                    |\n\n### Formatting\n\nSpecLynx OpenAPI Toolkit is capable of formatting your OpenAPI Documents, whether they are written\nin JSON or YAML. Formatting preferences, like `tabSize` or whether to use tabs or spaces (`insertSpaces`)\nare read directly from your VSCode settings.\n\n![JSON/YAML Formatting](https://github.com/user-attachments/assets/06f21516-7380-4e47-ac77-31a515cd1885)\n\n\n### Preview\n\nThe Preview panel (powered by [SwaggerUI](https://github.com/swagger-api/swagger-ui)) renders the current OpenAPI document and lets you interact with it.\nPreview panel can be opened by opening the Command Palette (CTRL+Shift+P) and running the `OpenAPI Toolkit: Show API Document preview` command.\n\n![SpecLynx OpenAPI Toolkit Preview](https://github.com/user-attachments/assets/67c4e9a9-9084-41ab-bbbe-a01bb50d3457)\n\n\nPreview interactions include:\n\n* **Live rendering** — Quickly verify how changes look without leaving the editor\n* **Server selection \u0026 auth** — Choose servers and authorize requests where applicable\n* **Try it out** — Execute operations directly from the preview to validate requests/responses during development\n\nThis helps you validate the specification from both a structural and a consumer point of view.\u0026#x20;\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeclynx%2Fvscode-openapi-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeclynx%2Fvscode-openapi-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeclynx%2Fvscode-openapi-toolkit/lists"}