API Hub for Design Plugin for IntelliJ IDEA

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

Features

  • View and navigate APIs or domains from your API Hub for Design organizations.Manage Resource Access

  • Edit and save APIs to API Hub for Design.

  • Create new APIs and domains from scratch or using a template.

  • Create new versions of your APIs and domains.Versioning

  • Publish and unpublish versions.

  • Change visibility of your APIs and domains.Public and Private APIs

  • Validate your APIs against the OpenAPI 3.0 and 2.0 schemas.

  • Add API mocks for quick definition testing.API Auto Mocking

Requirements

IntelliJ IDEA version 2020.3 or later.

Installation

You can install the API Hub for Design 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 – Leave the default value, https://api.swaggerhub.com.

  • API Key – Specify your API Hub for Design API key found at https://app.swaggerhub.com/settings/apiKey.

  • Additional headers – Optional. Custom HTTP headers and values that will be passed along in network calls to the API Hub for Design server. Use the and buttons to add and delete headers.

  • User's organizations – Add the names of API Hub for Design 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 API Hub for Design panel is hidden, you can click its tab or go to View > Tool Windows > API Hub for Design 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 API Hub for Design 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

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 API Hub for Design automatically. You need to right-click an API or domain version and select Sync to API Hub for Design.

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 API Hub for Design specification version. A new version will be created and saved to API Hub for Design.

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 API Hub for Design, 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 API Hub for Design documentation.API Auto Mocking

To create a mock, select API Hub for Design > 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

API Hub for Design 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 API Hub for Design

If you want to refresh an API or domain and its versions from API Hub for Design, click in the API Hub for Design 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 API Hub for Design 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 API Hub for Design 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 API Hub for Design 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:

go.gifhttps://github.com/SmartBear/intellij-swaggerhub-release/issues

See Also

Publication date: