Document Your OpenAPI Specification with the New Visual SwaggerHub Editor

Document Your OpenAPI Specification with the New Visual SwaggerHub Editor

We are thrilled to announce new enhancements that will make it easier for organizations to write API documentation and share public API docs in SwaggerHub.

New visual editor for documenting OAS definitions

You can now edit API information and metadata without needing to work directly in the YAML editor in SwaggerHub.

The new visual editing experience is perfect for team members that may not have direct knowledge of the YAML syntax or for technical writers that need to build out important details within your OAS definition like API information (title, description, license, contact information) or operational metadata (summary, description, tags).

Changes made in the visual editor will automatically sync with the YAML code editor and will be visualized in the UI view in real-time. The editor also supports markdown syntax, allowing different formats and styles to be applied to technical documentation that may be cumbersome to describe in the YAML editor.

Note: This is the first release of the visual editor in SwaggerHub. In the future, we will be adding enhanced functionality for describing endpoints, headers, bodies, and more.

Accessing the new Visual Editor

To switch to the Visual Editor, click Show Visual Editor in the sidebar of the SwaggerHub editor. If the cursor is inside a specific operation in the YAML code, Visual Editor will open for that operation.

Open-Visual-Editor.png

Select an item in the Navigation panel on the left. If the Navigation panel is hidden, click the Show Visual Editor icon in the sidebar to show it.

visual-editor-api-info.png

Explore the New Visual Editor

Add company logo and branding to Swagger UI docs

Organizations can now add their own branding to their API documentation hosted in SwaggerHub. The new customizable docs feature is perfect for organizations that are leveraging SwaggerHub to share documentation for external APIs.

The new functionality lets organizations upload their company logo to replace the standard SwaggerHub logo and customize the header colors to match their corporate branding.

Custom-Docs-Example.png

Docs Branding is available to organizations on the Team and Enterprise plans.

Accessing new Docs Branding feature

The organization owner can configure the branding options on the Docs Branding page of the organization settings:

  1. Click your username and select Settings.
  2. Switch to the My Organizations tab.
  3. Select Docs Branding in the sidebar on the left.

Docs-Branding.png

Explore the New Docs Branding Functionality

Integration with Azure DevOps Services

The new Azure DevOps Services integration lets you synchronize your API definition, auto-generated server code, or client SDK with an existing Git repository in Azure DevOps Services (formerly Visual Studio Team Services or VSTS). Every time you save your API in SwaggerHub, the integration will update the code in the specified repository.

The integration with Azure DevOps Services is the latest source control integration added to SwaggerHub, along with the existing integrations with GitHub, GitLab, and Bitbucket.

Accessing the new integration:

  1. Open your OAS 2.0 or OAS 3.0 definition in the SwaggerHub editor.
  2. If the API has several versions, select the version you want to synchronize with your repository in Azure DevOps Services.

Open-SwaggerHub-Integrations.png

  1. Click the API name to open the API Info panel.
  2. In the API Info panel, switch to the Integrations tab, and click Add New Integrations.

Add-New-Integration.png

  1. Select Azure DevOps Services from the list of integrations.

Explore the Azure DevOps Services Integration

Get started with SwaggerHub

All of these latest updates are available in SwaggerHub Team and Enterprise plans. Log in and try them for yourself or start your free trial today.