API Insights is an open-source tool developed by Cisco which helps developers improve API quality and security. While API Insights runs as a remote service, the API Insights Extension for Visual Studio Code allows developers to leverage the functionalities of API Insights within their local IDE.
Enhanced Productivity and Developer Experience
API Insights validates and scores API specifications against an organization’s guidelines on dimensions such as documentation completeness, API guidelines adherence, inclusive language, and runtime drift. This allows you to track and improve API quality consistently and efficiency.
Developers can use API Insights through its own dashboard interface, VS Code extension, local CLI, or as part of their GitHub CI/CD pipeline.
The CI/CD and VS Code extension capabilities of API Insights allow developers to Shift Left, allowing them to resolve spec issues early in the development cycle.
Leveraging API Insights as part of the code development process allows developers to detect and fix breaking changes, which significantly improves developer experience. The API Insights extension allows you to proactively detect and resolve issues within your local IDE.
Get Started
Installation
Download and install official Microsoft Visual Studio Code
API Insights extension for Visual Studio Code works in two different modes:
Local Mode - API Insights service is not connected
Validates local API specification files
Connected Mode - API Insights remote service is configured and connected
Validates and scores API specs - validates and scores API specifications against an organization’s guidelines. This allows developers to track and improve API quality consistently and efficiently.
API lifecycle management - provides a trend timeline of API quality, and generates both API changelogs and diff comparisons of API versions to identify breaking changes.
Connecting to API Insights service
If there is an API Insights remote service available, API Insights extension for Visual Studio Code can be configured to unlock features available in connected mode.
Setting Item
Default Value
Description
API Insights: Endpoint URL
<empty>
The API endpoint exposed by API Insights remote service, required for extension to call its API
API Insights: Auth Type
None
Three Authorization Types are availeble:
None: service is public, authentication is disabled
Token: using HTTP Authorization request header: Authorization : <Token Type> <Token Value> to authorize this extension, Token type is default to Bearer, token value is required
OAuth: using OAuth 2.0 Client Credentials flow to authorize this extension, Token URL, Client ID and Client Secret are all required
Development
Clone the repository and install dependencies
git clone https://github.com/cisco-developer/api-insights-extension-vscode
cd api-insights-extension-vscode
npm i
Open api-insights-extension-vscode folder in Visual Studio Code
Click 'Start Debugging' or 'Run Without Debugging' from Run menu
API Insights Extension for Visual Studio Code now runs in local mode, continue to setup an API Insights local instance to switch to connected mode:
git clone https://github.com/cisco-developer/api-insights
cd api-insights
docker-compose up
Now API Insights service is running at http://localhost:8081, open Settings in Visual Studio Code, set API Insights Endpoint URL to http://localhost:8081/v1/apiregistry/. For more information, please refer to API Insights and API Insights Official Documentation
