IntelliJ Platform

The OpenAPI Guard plugin for IntelliJ IDEA: inspections for Spring, Express, and AWS Lambda, quick fixes, the Operations tool window, and path completion.

Install OpenAPI Guard from JetBrains Marketplace, or from inside the IDE under Settings, Plugins, Marketplace. The plugin identifier is com.stackblender.openapiguard; the current release is 0.4.1.

It works in IntelliJ IDEA Community and Ultimate, 2024.1 and later. Ultimate’s Spring plugin is not required. OpenAPI 3.x in YAML or JSON is supported; Swagger 2.0 is not.

What it checks

OpenAPI Guard compares a local OpenAPI 3.x document with the endpoints your code implements and reports three kinds of drift: operations nobody implemented, endpoints the spec does not document, and HTTP methods that disagree. It reads:

• Spring MVC controllers in Java and Kotlin, including spec-first projects built with openapi-generator (interface and delegate styles).
• Express applications and routers in TypeScript or JavaScript: app and router routes, route() chains, and routers mounted with use() across files, with import, require, and module.exports.
• AWS Lambda handlers behind an API Gateway HTTP API, in TypeScript or JavaScript: route maps and switch statements dispatched on event.routeKey, including imported route maps and alias maps that resolve legacy routes to current ones. A custom router can declare its routes in an openapi-guard.routes.json file.

Test files, minified files, and TypeScript build output (the outDir of any tsconfig*.json) are skipped; an import of build output is followed to its source.

When OpenAPI Guard cannot read part of the routing, such as a computed path, a router no application mounts, or routeKey dispatch it does not recognize, it says so instead of guessing: the operations that code might serve are shown as Could not verify, not as missing.

The first time analysis works on a project, a one-time notification shows the coverage summary. If Spring controllers exist but no spec was found, it says how to add one.

Inspections

Drift is reported by three standard inspections under Settings, Editor, Inspections, OpenAPI Guard: Endpoint not documented in OpenAPI, OpenAPI operation has no implementation, and HTTP method differs between OpenAPI and implementation. A fourth, OpenAPI Guard analysis limitation (a weak warning), marks the mappings and routes it could not analyze. Each can be enabled or given its own severity, and they run in Code, Inspect Code. In TypeScript and JavaScript files, a problem is highlighted on the route’s line.

To mark drift as intentional, use @SuppressWarnings("OpenApi…") in Java or @Suppress("OpenApi…") in Kotlin on a method or class; springdoc’s @Hidden or @Operation(hidden = true) marks an endpoint as deliberately undocumented; and x-openapi-guard-ignore: true on an operation, a path item, or the spec root exempts those operations from missing-implementation checks.

Quick fixes

Press Alt+Enter on a reported line:

• Add operation to OpenAPI spec, on an undocumented endpoint, inserts a YAML stub with the path, an operationId from the handler name, path parameters, and a 200 response, matching the spec’s indentation. The preview shows the spec diff.
• Implement in Spring controller, on a missing operation, adds a mapped handler stub to the controller whose base path best matches, in Java or Kotlin, with imports. When the controller inherits its mappings from a hand-written API interface or base class, the declaration is added there and the controller gets an override stub.
• Change mapping to X or Change operation to X, on a method mismatch, aligns the HTTP method on whichever side you choose.

Fixes are not offered where the mapping lives in generated code, such as an openapi-generator interface: regenerate, then implement the new method. Quick fixes work on Spring code and on the spec; Express and Lambda routes are reported and navigable, without fixes.

Operations tool window

The OpenAPI Guard tool window lists every operation with its status: implemented, missing, method mismatch, ignored, or could not verify, plus undocumented endpoints. The summary line reads, for example, “7 of 9 operations implemented (77%) · 1 missing · 1 method mismatch · 1 undocumented”.

• The search field filters rows on any column, and combines with Show Problems Only.
• Double-click the Spec or Implementation cell to open that side. Enter or a double-click elsewhere opens the implementation, or the spec when there is none. Right-click a row for Go to Implementation and Go to Spec.
• A Could not verify row shows the analysis limitation behind it and opens it. The summary counts limitations (“N analysis limitations — missing implementations not reported”), and Go to Analysis Limitation on the toolbar opens them.
• The window refreshes in the background after edits and as soon as settings change.

Copy as Markdown on the toolbar copies the summary and the rows currently shown as a Markdown table, honoring the search and the problems-only filter and noting any active filter, ready for a pull request, an issue, or a review. Copy Selected as Markdown in the row menu copies just the selected rows.

Path completion

Inside @GetMapping("…"), @RequestMapping("…"), and the other mapping annotations, in Java and Kotlin, completion offers paths from the spec relative to the controller’s base path and filtered to the annotation’s HTTP method. Operations that have no implementation yet are listed first, in bold. A class-level @RequestMapping offers resource paths.

Navigation

Gutter icons and Go to Declaration (Ctrl+B or Ctrl+click; ⌘B or ⌘+click on macOS) work in both directions between an OpenAPI operation and its implementation: a Spring mapping, an Express route, or a Lambda route registration.

Specs and settings

Specs are found by content: any YAML or JSON file whose root has an openapi: 3.x key, whatever its name. Test sources, node_modules, and generated output are ignored. A project can have several specs; each is checked against its own module and the modules that depend on it, and modules without a spec produce no warnings.

Settings, Tools, OpenAPI Guard lets you list explicit spec paths, one per line, which replace automatic discovery, and turn contract analysis off altogether. Changes apply immediately. A configured path that does not exist is reported in a notification when the project opens and in the tool window. A spec that cannot be analyzed (for example one with a remote $ref, or a Swagger 2.0 document) gets a banner in its editor with the reason, and is listed in the tool window as well.

Privacy

Analysis runs entirely on your machine. The plugin never uploads source code, specifications, or diagnostics, and needs no account or network access.

What’s new in 0.4

• Express and AWS Lambda (API Gateway) routes, in TypeScript and JavaScript, with highlighting on the route’s line and gutter navigation to their operations.
• The OpenAPI Guard analysis limitation inspection, and Could not verify rows in the Operations tool window, where code cannot be analyzed.
• Inspection names no longer say “Spring”; suppression IDs are unchanged.
• 0.4.1: TypeScript build output is skipped, imports of build output resolve to their sources, legacy route aliases are scoped by their target’s module, and the Operations summary counts analysis limitations.

The full history is in the plugin’s change notes on JetBrains Marketplace.

Report problems through the support repository and select the IntelliJ Platform plugin.

×