如果您正在开发 RESTful 应用程序并开发 REST API 或在您的代码中使用它们,您可能已经了解 OpenAPI 和 Swagger。
如果您还不熟悉它,Swagger 是一组工具,可帮助您为 API 创建文档(Swagger 网站有丰富的信息,欢迎您查看),而 OpenAPI 是一种描述端点的格式 REST API。
在这篇博文中,我们将了解 WebStorm 如何帮助您创建和编辑 API 文档、使用 API 调用编写代码以及测试调用。
首先,我们需要安装 OpenAPI Specifications 插件。 从插件存储库或 IDE 设置中的 Marketplace 选项卡安装插件。
在项目添加 OpenAPI 规范
要在您的项目中创建新的 API 规范,请使用 File | New… 菜单或项目视图中的 New… 弹出窗口,然后选择 OpenAPI 规范。 您可以在 JSON 和 YAML 之间进行选择。
WebStorm 将在代码完成弹出窗口中向您显示带有简短描述的部分名称,IDE 还将检查该文件是否包含所有必需的部分。
如果您已有 OpenAPI 规范,则可以直接在 IDE 中查看使用 Swagger UI 构建的一些文档。 使用编辑器右上角的图标在编辑和预览模式之间切换。 此文档是交互式的,您可以直接从该预览版中测试端点。
代码中 API 的补全
规范文件最重要的部分是列出可用端点及其支持的 HTTP 方法的路径部分。 一旦您在项目中的任何位置拥有规范文件,您就可以在 JavaScript 和 TypeScript 代码中看到这些 API 的建议。
目前,它们在两种情况下显示:
- 在 fetch() 方法调用中,以及
- 使用 axios 库中的 get() 或 post() 等方法时。
在您的项目中拥有正确的 OpenAPI 规范并不是从这些完成建议中受益的唯一方法——您还可以指定一个可用规范的 URL。 为此,请转到 Preferences/Settings | Languages and Frameworks | OpenAPI Specification, 单击加号图标,然后将链接粘贴到 JSON 或 YAML 文件。
如果您正在使用某些第三方服务的 API,您可以在 GitHub 上的 openapi-directory 存储库(在 APIs 文件夹中)检查是否有社区维护的 OpenAPI 规范。 如果有,请获取到规范文件的直接链接,然后在IDE 首选项/设置中添加该 URL。
使用 HTTP 客户端测试 API 调用
您可能已经知道,WebStorm 有一个内置的 HTTP 客户端,您可以使用它来测试 REST API。
从 OpenAPI 规范文件中,您可以通过单击方法旁边的图标以 HTTP 客户端理解的格式快速生成新请求。 然后,您可以根据需要使用代码完成建议添加其他参数。
或者,您可以直接使用 JavaScript 或 TypeScript 文件中的意图创建新请求。 当插入符号位于 fetch 或 axios 方法中的 URL 上时,按 Alt+Enter,然后选择生成请求。
您可以将 auth token 和 任何其他环境变量 存储在一个特殊的 http-client.private.env.json
文件中——在 WebStorm 文档中可以找到更多关于它的信息。
该插件有更多有用的功能,您可以尝试; 我将重点介绍其中两个。 一种是与 OpenAPI 代码生成器集成,您可以使用它来创建基于 API 规范的库。 另一个是 Compare with Last Specification Revision 操作,您可以从 Find Action 弹出窗口 (Cmd/Ctrl+Shift+A) 中调用它,并使用它来查找项目中 OpenAPI 规范中引入的任何重大更改。