Swagger Studio Plugin for IntelliJ IDEA

Swagger Studio has a plugin for IntelliJ IDEA that lets you view and edit your OpenAPI definitions stored in Swagger Studio directly from the IDE. You can access your organization’s APIs and domains and sync the changes back to Swagger Studio.

Features

View and navigate APIs or domains from your Swagger Studio organizations.
Edit and save APIs to Swagger Studio.
Create new APIs and domains from scratch or using a template.
Create new versions of your APIs and domains.
Publish and unpublish versions.
Change visibility of your APIs and domains.
Validate your APIs against the OpenAPI 3.0 and 2.0 schemas.
Add API mocks for quick definition testing.

Requirements

IntelliJ IDEA version 2020.3 or later.

Installation

You can install the Swagger Studio plugin from the Settings dialog in IntelliJ IDEA.

From the IntelliJ IDEA main menu, select File > Settings.
Select Plugins from the settings tree.
Select the Marketplace tab.
Search for SwaggerHub.
Click Install.
After the installation is complete, restart the IDE.

Get started

1. Configure the plugin

Configure the plugin before starting using it. Click to open the settings:

API endpoint root – If you use Swagger Studio On-Premise, change the value to http(s)://YOUR_SERVER/v1. Swagger Studio SaaS users should leave the default value, https://api.swaggerhub.com.
API Key – Specify your Swagger Studio API key found at https://app.swaggerhub.com/settings/apiKey or at http(s)://YOUR_SERVER/settings/apiKey if you use Swagger Studio On-Premise.
Additional headers – Optional. Custom HTTP headers and values that will be passed along in network calls to the Swagger Studio server. This may be needed in some Swagger Studio On-Premise network architectures, for example, if the server is located behind a secure proxy that requires specific headers. Use the and buttons to add and delete headers.
User's organizations – Add the names of Swagger Studio organizations whose APIs and domains you want to access. You can also add your username to the list to access definitions created in your personal account. Use the and buttons to add and delete organizations or usernames.

2. Load and work with your APIs

After configuring the plugin, the Swagger Studio panel will appear in the IDE on the left. All specified organizations and their APIs and domains will be shown in it.

If the Swagger Studio panel is hidden, you can click its tab or go to View > Tool Windows > Swagger Studio to open it.

Commands specific to a version of an API or domain are available in the editor context menu when this version is opened.

Use the plugin

Create an API or domain

If you want to create an API or domain from scratch or using a template, click in the Swagger Studio sidebar. In the dialog that opens, specify your API or domain details: name, OAS version, owner, and others. Select the Auto Mock API check box to add a mock server for your API.Creating a New APIAPI Auto Mocking

Note

Changes made in an API or domain version and saved via Ctrl+S or File > Save All are not saved to Swagger Studio automatically. You need to right-click an API or domain version and select Sync to Swagger Studio.

Create a new version of an API or domain

Right-click a version of an API or domain and select New Swagger Studio specification version. A new version will be created and saved to Swagger Studio.

Set the default version

If an API or domain has several versions, the default one has the icon in the list. To make another version the default one, right-click that version and select Set Version Default.

Preview an API in Swagger UI

When you are editing an API definition, a Swagger UI preview of the API documentation appears on the right side. The preview is updated automatically on save. You can also update the preview manually by clicking in the top right corner of the editor.

In Swagger UI, you can also test the requests by using the Try it out button. For this to work, your API definition needs to include the servers or host (either a live server or a mock server).

You can toggle between the editor-only, preview-only, and split views by using the buttons in the top right corner of the window.

Auto Mocking

With Swagger Studio, you can quickly create a mock of your API. Mocks are handy for quick prototyping and integration testing. For more information, see API Auto Mocking in the Swagger Studio documentation.API Auto Mocking

To create a mock, select Swagger Studio > Add Auto Mocking integration from the editor context menu. The mock server is added to the servers list or the host/basePath keys in your API definition. You can then test the requests and see mock responses in Swagger UI.

Change the visibility or status

If you want to change the visibility (public or private) or status (published or unpublished) of an API or domain version, right-click this version and select the corresponding menu commands.

Check the syntax

The plugin checks YAML formatting and validates your APIs against the OpenAPI 3.0 and 2.0 schemas to detect errors such as missing required keywords or misspelled keywords. The number of errors is displayed in the upper right of the editor bar. Click that number to open the Problems view containing the full list of errors, from where you can jump to the corresponding lines in the editor.

Delete APIs, domains, or versions

Right-click an API or domain version and select Delete Version to delete a specific version. You can't delete it if this is the only version of the API or domain.

If you want to delete an API or domain, right-click the API or domain and select Delete Definition.

Reload from Swagger Studio

If you want to refresh an API or domain and its versions from Swagger Studio, click in the Swagger Studio panel.

To refresh versions of an API or domain, right-click the API or domain and select Refresh All Versions for Spec.

Select Pull latest from Swagger Studio in the API or domain version context menu to refresh the version of an API or domain.

Scroll to the opened file

If you want to jump to an opened version of an API or domain in the Swagger Studio panel, click Locate button in the panel.

Find an API or domain

If you need to find an API or domain by the name, select the top item in the Swagger Studio panel, then start typing a name to find the matching definitions.

Questions and feedback

If you have any questions, suggestions or want to report a bug, please open an issue here:

https://github.com/SmartBear/intellij-swaggerhub-release/issues