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.
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.
IntelliJ IDEA version 2020.3 or later.
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.
After the installation is complete, restart the IDE.
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,
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.
If the SwaggerHub panel is hidden, you can click its tab or go to View > Tool Windows > SwaggerHub 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 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.
|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.|
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.
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
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.
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.|
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 SwaggerHub
If you want to refresh an API or domain and its versions from SwaggerHub, click in the SwaggerHub 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 SwaggerHub 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 SwaggerHub panel, click 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 SwaggerHub 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: