Working With REST APIs in WebStorm
If you aren’t already familiar with it, Swagger is a set of tools that helps you create docs for APIs (their website has a wealth of information that you’re welcome to check out), while OpenAPI is a format for describing the endpoints of the REST API.
In this blog post, we’ll have a look at how WebStorm can help you create and edit API docs, write code with API calls, and test the calls.
To get started, we’ll need to install the OpenAPI Specifications plugin. Install it from the plugin repository or from the Marketplace tab in IDE Settings | Plugins.
Adding an OpenAPI spec to the project
To create a new API spec in your project, use the File | New… menu or the New… popup in the Project View, and then select OpenAPI Specification. You can choose between JSON and YAML.
WebStorm will show you the names of sections with a short description in the code completion popup, and the IDE will also check that the file has all the required sections.
If you already have an OpenAPI spec, you can see some docs built with Swagger UI right in the IDE. Switch between editing and preview modes using the icons in the top right corner of the editor. This documentation is interactive, and you can test the endpoints right from this preview.
Completion for APIs in the code
The most important part of the spec file is the
Currently, they are shown in two situations:
We’re planning to add support for Express methods soon.
Having an OpenAPI spec right in your project is not the only way to benefit from these completion suggestions – you can also specify a URL where the spec is available. For that, go to Preferences/Settings | Languages and Frameworks | OpenAPI Specification, click the plus icon, and then paste the link to the JSON or YAML file.
If you’re using APIs of some 3rd-party service, you can check if there’s a community-maintained OpenAPI spec for it in the openapi-directory repository on GitHub (in the APIs folder). If there is one, grab a direct link to the spec file and add that URL in the IDE Preferences/Settings.
Testing API calls with the HTTP Client
As you may already know, WebStorm has a built-in HTTP client that you can use to test REST APIs.
From the OpenAPI spec file, you can quickly generate new requests in the format that the HTTP Client understands by clicking on the icon next to the method. You can then use code completion suggestions to add additional parameters if needed.
Alt+Enter when the caret is on the URL in the fetch or axios method and then select Generate request.
You can store the auth token and any other env variables in a special
http-client.private.env.json file – find our more about that in the WebStorm docs.
The plugin has more useful features you can try; I’ll highlight two of them. One is integration with the OpenAPI Code Generator, which you can use to create a library based on the API spec. The other is a Compare with Last Specification Revision action, which you can invoke from the Find Action popup (
Cmd/Ctrl+Shift+A) and use to find any breaking changes introduced in the OpenAPI spec in your project.
The WebStorm team