SwaggerHub Plugin for IntelliJ IDEA
SwaggerHub has a plugin for IntelliJ IDEA that lets you view and edit your OpenAPI definitions stored in SwaggerHub directly from the IDE. You can access your organization’s APIs and domains and sync the changes back to SwaggerHub.
Both SwaggerHub SaaS and On-Premise are supported.
Features
View and navigate APIs or domains from your SwaggerHub organizations.
Edit and save APIs to SwaggerHub.
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 SwaggerHub 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 the image to enlarge it.
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 SwaggerHub On-Premise, change the value to
http(s)://YOUR_SERVER/v1. SwaggerHub SaaS users should leave the default value,https://api.swaggerhub.com.API Key – Specify your SwaggerHub API key found at https://app.swaggerhub.com/settings/apiKey or at
http(s)://YOUR_SERVER/settings/apiKeyif you use SwaggerHub On-Premise.Additional headers – Optional. Custom HTTP headers and values that will be passed along in network calls to the SwaggerHub server. This may be needed in some SwaggerHub 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 SwaggerHub 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 SwaggerHub panel will appear in the IDE on the left. All specified organizations and their APIs and domains will be shown in it.
 |
Click the image to enlarge it.
If the SwaggerHub panel is hidden, you can click its tab or go to View > Tool Windows > SwaggerHub to open it.
 |
Click the image to enlarge it.
Commands specific to a version of an API or domain are available in the editor context menu when this version is opened.
 |
Click the image to enlarge it.
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 SwaggerHub 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.
 |
Click the image to enlarge it.
Note
Changes made in an API or domain version and saved via Ctrl+S or File > Save All are not saved to SwaggerHub automatically. You need to right-click an API or domain version and select Sync to SwaggerHub.
 |
Click the image to enlarge it.
Create a new version of an API or domain
Right-click a version of an API or domain and select New SwaggerHub specification version. A new version will be created and saved to SwaggerHub.
 |
Click the image to enlarge it.
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.
 |
Click the image to enlarge it.
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).
 |
Click the image to enlarge it.
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 SwaggerHub, 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 SwaggerHub documentation.
To create a mock, select SwaggerHub > 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.
Note
SwaggerHub On-Premise users need v. 1.26 or later to add mocks from within the IntelliJ plugin.
 |
Click the image to enlarge it.
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.
 |
Click the image to enlarge it.
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.
 |
Click the image to enlarge it.
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.
 |
Click the image to enlarge it.
If you want to delete an API or domain, right-click the API or domain and select Delete Definition.
 |
Click the image to enlarge it.
Reload from SwaggerHub
If you want to refresh an API or domain and its versions from SwaggerHub, click in the SwaggerHub panel.
 |
Click the image to enlarge it.
To refresh versions of an API or domain, right-click the API or domain and select Refresh All Versions for Spec.
 |
Click the image to enlarge it.
Select Pull latest from SwaggerHub in the API or domain version context menu to refresh the version of an API or domain.
 |
Click the image to enlarge it.
Scroll to the opened file
If you want to jump to an opened version of an API or domain in the SwaggerHub panel, click 
in the panel.
 |
Click the image to enlarge it.
Find an API or domain
If you need to find an API or domain by the name, select the top item in the SwaggerHub panel, then start typing a name to find the matching definitions.
 |
Click the image to enlarge it.
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