SwaggerHub Extension for Visual Studio Code

The SwaggerHub extension lets you view and edit your OpenAPI definitions stored in SwaggerHub directly from Visual Studio Code. 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 definitions from your SwaggerHub organizations.
Edit and save definitions to SwaggerHub.
Create new APIs and domains from scratch or using a template.
Create new versions of your APIs and domains.
Preview your APIs in Swagger UI.
Delete definitions by the version or the entire definition.
Validate your definitions against the OpenAPI 3.0 and 2.0 schemas.
Add API mocks for quick definition testing.

Requirements

VS Code version 1.50.0 or later.

Get started

1. Configure the extension

Before using the SwaggerHub extension, you need to configure its settings:

Setting	Description
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.
Custom Headers	Additional 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. To delete or edit an entry, hover over it and use the buttons that appear.
Destination	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`.
Orgs	Add the names of SwaggerHub organizations that you want to access. You can also add your username to the list to access definitions created in your personal account. To delete or edit an entry, hover over it and use the buttons that appear.

2. Load & work with your API definitions

Click on the left-hand side to open the SwaggerHub extension. You will see a list of APIs and domains from the connected organizations.

Select an API or domain to view or edit it:

Open an API

The selected definition is downloaded to a temporary folder on your computer. When you save the changes in the editor, the updated definition is uploaded back to SwaggerHub.

Use the extension

Create an API or domain

You can create new API definitions and domains from scratch or using a template. To do this, click at the top of the SwaggerHub APIs or SwaggerHub Domains panels and follow the prompts.

Create an API definition

Create a new version of an API or domain

Open a definition in the editor, change its info.version value, and save the changes. A new version will be created and saved to SwaggerHub.

Create a new version

Set the default version

If an API or domain has several versions, the default version has the icon in the list. To make another version the default one, open that version in the editor and select SwaggerHub > Make default from the context menu.

Change the default version

Preview an API in Swagger UI

To see how your API documentation looks in Swagger UI, click in the top right corner of the editor or select SwaggerHub > Preview in Swagger UI from the context menu. The preview is updated automatically as you make changes in the editor.

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

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 to add mocks from within the VS Code extension.

Auto Mocking integration

Change the visibility or status

The visibility (public or private) and status (published or unpublished) of the current definition is displayed in the VS Code status bar. Use the editor context menu to change the visibility and status.

Change status

Check the syntax

The extension checks YAML formatting and validates your definitions 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 status 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 error example

Delete APIs, domains, or versions

Click next to a specific version to delete it. If this is the only version, you will be prompted to delete the entire API or domain.

Delete an API

Reload from SwaggerHub

To reload the list of APIs, domains, and their versions from SwaggerHub, click at the top of the list.

You can also reload the version list for a specific definition by clicking next to it.

Refresh an API

Tips

Find and filter APIs and domains

The SwaggerHub APIs and SwaggerHub Domains panels support VS Code's "filter on type" feature to find and filter definitions. Select the top item, then start typing a name to find the matching definitions. Optionally, you can click Enable Filter on Type in the filter box to see only matching definitions.

Filter on Type

Peek definition

To preview the referenced definition inline, right-click the $ref value and select Peek > Peek Definition from the context menu.

Peek a definition

Jump to a reference

To navigate to the referenced definition, Ctrl-click the $ref value or right-click it and select Go to Definition from the context menu.

Go to a definition

Questions and feedback

If you have any questions, suggestions or want to report a bug, please open an issue here:
https://github.com/SmartBear/vscode-swaggerhub-release/issues

SwaggerHub for VS Code

SmartBear Software