SwaggerHub Plugin for IntelliJ IDEA

Last modified on September 23, 2022

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.

  1. From the IntelliJ IDEA main menu, select File > Settings.

  2. Select Plugins from the settings tree.

  3. Select the Marketplace tab.

  4. Search for SwaggerHub.

    Installing the SwaggerHub plugin into IntelliJ IDEA

    Click the image to enlarge it.

  5. Click Install.

  6. 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/apiKey if 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.

SwaggerHub plugin for IntelliJ IDEA

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.

Plugin panel in IDE

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.

Editor context menu

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.

New 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.
Sync changes

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.

New API version

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.

Set default version

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).

API documentation preview in Swagger UI

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.

View mode toggle buttons

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.
Add auto mocking

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.

Change API status or visibility

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.

Syntax check

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.

Delete API version

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.

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.

Refresh definitions button

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.

Refresh API versions

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.

Pull latest changes button

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 Locate button in the panel.

Scroll to opened file

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.

Find an API or domain

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

See Also

SwaggerHub Integrations
SwaggerHub Maven Plugin
SwaggerHub Gradle Plugin

Highlight search results