Working With REST APIs in WebStorm
If you’re working on a RESTful application and either developing REST APIs or using them in your code, you might already know about OpenAPI and Swagger.
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 paths
section that lists available endpoints and their supported HTTP methods. Once you have a spec file anywhere in your project, you’ll be able to see suggestions for these APIs in your JavaScript and TypeScript code.
Currently, they are shown in two situations:
- in
fetch()
method calls, and - when using methods like
get()
orpost()
from the axios library.
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.
Alternatively, you can create new requests using an intention right from the JavaScript or TypeScript file. Press 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