| title | description | author | ms.service | ms.topic | ms.date | ms.author | ms.custom |
|---|---|---|---|---|---|---|---|
Govern APIs - VS Code extension | API developers can use the Azure API Center extension for Visual Studio Code to govern their organization's APIs. | dlepow | azure-api-center | how-to | 10/16/2024 | danlep |
To maximize success of your API governance efforts, it's critical to shift-left governance early into the API development cycle. This approach allows API developers to create APIs correctly from the beginning, saving them from wasted development effort and mitigating noncompliant APIs later in the development process.
The Azure API Center extension for Visual Studio Code includes the following governance capabilities for API developers:
- Evaluating API designs against API style guides as the API is developed in Visual Studio Code.
- Early detection of breaking changes so that APIs remain reliable and function as expected, preserving the trust of end-users and stakeholders.
API developers can also take advantage of features in the extension to register APIs in the API center and discover and consume APIs.
[!INCLUDE vscode-extension-basic-prerequisites]
- Spectral extension for Visual Studio Code - to run shift-left API design conformance checks in Visual Studio Code
- Optic CLI - to detect breaking changes between API specification documents
[!INCLUDE vscode-extension-setup]
To ensure design conformance with organizational standards as you build APIs, the Azure API Center extension for Visual Studio Code provides integrated support for API specification linting with Spectral.
- Use the Ctrl+Shift+P keyboard shortcut to open the Command Palette. Type Azure API Center: Set active API Style Guide and hit Enter.
- Select one of the default rules provided, or, if your organization has a style guide already available, use Select Local File or Input Remote URL to specify the active ruleset in Visual Studio Code. Hit Enter.
Once an active API style guide is set, opening any OpenAPI or AsyncAPI-based specification file triggers a local linting operation in Visual Studio Code. Results are displayed both inline in the editor and in the Problems window (View > Problems or Ctrl+Shift+M).
:::image type="content" source="media/govern-apis-vscode-extension/local-linting.png" alt-text="Screenshot of local-linting in Visual Studio Code." lightbox="media/govern-apis-vscode-extension/local-linting.png":::
When introducing new versions of your API, it's important to ensure that changes introduced do not break API consumers on previous versions of your API. The Azure API Center extension for Visual Studio Code makes this easy with breaking change detection for OpenAPI specification documents powered by Optic.
- Use the Ctrl+Shift+P keyboard shortcut to open the Command Palette. Type Azure API Center: Detect Breaking Change and hit Enter.
- Select the first API specification document to compare. Valid options include API specifications found in your API center, a local file, or the active editor in Visual Studio Code.
- Select the second API specification document to compare. Valid options include API specifications found in your API center, a local file, or the active editor in Visual Studio Code.
Visual Studio Code opens a diff view between the two API specifications. Any breaking changes are displayed both inline in the editor and in the Problems window (View > Problems or Ctrl+Shift+M).
:::image type="content" source="media/govern-apis-vscode-extension/breaking-changes.png" alt-text="Screenshot of breaking changes detected in Visual Studio Code." lightbox="media/govern-apis-vscode-extension/breaking-changes.png":::
