Merge pull request #288597 from MicrosoftDocs/main

10/17 11:00 AM IST Publish

Author: PhilKang0704

articles/api-center/TOC.yml

@@ -46,6 +46,8 @@
   items:
       - name: Use metadata for governance
         href: metadata.md
+      - name: Govern APIs - VS Code extension
+        href: govern-apis-vscode-extension.md
       - name: API analysis - Microsoft managed
         href: enable-managed-api-analysis-linting.md
       - name: API analysis - self-managed
@@ -56,6 +58,8 @@
         href: find-nonproduction-api-requests-dev-proxy.md
 - name: API discovery and consumption
   items:
+      - name: Discover and consume APIs - VS Code extension
+        href: discover-apis-vscode-extension.md
       - name: Enable platform API catalog - VS Code extension
         href: enable-platform-api-catalog-vscode-extension.md
       - name: Self-host Azure API Center portal

articles/api-center/build-register-apis-vscode-extension.md

@@ -0,0 +1,112 @@
+---
+title: Discover APIs - VS Code extension
+description: API developers can use the Azure API Center extension for Visual Studio Code to discover APIs in their organization's API center.
+author: dlepow
+ms.service: azure-api-center
+ms.topic: how-to
+ms.date: 10/16/2024
+ms.author: danlep 
+ms.custom: 
+# Customer intent: As an API developer, I want to use my Visual Studio Code environment to discover and consume APIs in my organizations API center.
+---
+
+# Discover and consume APIs with the Azure API Center extension for Visual Studio Code
+
+API developers in your organization can discover and consume APIs in your [API center](overview.md) by using the Azure API Center extension for Visual Studio Code. The extension provides the following features:
+
+* **Discover APIs** - Browse the APIs in your API center, and view their details and documentation.
+
+* **Consume APIs** - Generate API SDK clients in their favorite language including JavaScript, TypeScript, .NET, Python, and Java, using the Microsoft Kiota engine that generates SDKs for Microsoft Graph, GitHub, and more. 
+
+API developers can also take advantage of features in the extension to [register APIs](build-register-apis-vscode-extension.md) in the API center and ensure [API governance](govern-apis-vscode-extension.md).
+
+> [!TIP]
+> If you want enterprise app developers to discover APIs in a centralized location, optionally enable a [platform API catalog](enable-platform-api-catalog-vscode-extension.md) for your API center in Visual Studio Code. The platform API catalog is a read-only view of the API inventory.
+
+[!INCLUDE [vscode-extension-basic-prerequisites](includes/vscode-extension-basic-prerequisites.md)]  
+    
+* [REST client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) - to send HTTP requests and view the responses in Visual Studio Code directly
+* [Microsoft Kiota extension](https://marketplace.visualstudio.com/items?itemName=ms-graph.kiota) - to generate API clients
+
+[!INCLUDE [vscode-extension-setup](includes/vscode-extension-setup.md)]   
+
+## Discover APIs
+
+API center resources appear in the tree view on the left-hand side. Expand an API center resource to see APIs, versions, definitions, environments, and deployments.
+
+:::image type="content" source="media/discover-apis-vscode-extension/explore-api-centers.png" alt-text="Screenshot of API Center tree view in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/explore-api-centers.png":::
+
+Search for APIs within an API Center by using the search icon shown in the **Apis** tree view item.
+
+## View API documentation
+
+You can view the documentation for an API definition in your API center and try API operations. This feature is only available for OpenAPI-based APIs in your API center.
+
+1. Expand the API Center tree view to show an API definition. 
+1. Right-click on the definition, and select **Open API Documentation**. A new tab appears with the Swagger UI for the API definition.
+
+    :::image type="content" source="media/discover-apis-vscode-extension/view-api-documentation.png" alt-text="Screenshot of API documentation in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/view-api-documentation.png":::
+
+1. To try the API, select an endpoint, select **Try it out**, enter required parameters, and select **Execute**.
+
+    > [!NOTE]
+    > Depending on the API, you might need to provide authorization credentials or an API key to try the API.
+
+    > [!TIP]
+    > Using the pre-release version of the extension, you can generate API documentation in Markdown, a format that's easy to maintain and share with end users. Right-click on the definition, and select **Generate Markdown**.
+
+## Generate HTTP file
+
+You can view a `.http` file based on the API definition in your API center. If the REST Client extension is installed, you can make requests directory from the Visual Studio Code editor. This feature is only available for OpenAPI-based APIs in your API center.
+
+1. Expand the API Center tree view to show an API definition. 
+1. Right-click on the definition, and select **Generate HTTP File**. A new tab appears that renders a .http document populated by the API specification.
+
+    :::image type="content" source="media/discover-apis-vscode-extension/generate-http-file.png" alt-text="Screenshot of generating a .http file in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/generate-http-file.png":::
+
+1. To make a request, select an endpoint, and select **Send Request**.
+
+    > [!NOTE]
+    > Depending on the API, you might need to provide authorization credentials or an API key to make the request.
+
+## Generate API client
+
+Use the Microsoft Kiota extension to generate an API client for your favorite language. This feature is only available for OpenAPI-based APIs in your API center.
+
+1. Expand the API Center tree view to show an API definition.    
+1. Right-click on the definition, and select **Generate API Client**. The **Kiota OpenAPI Generator** pane appears.
+1. Select the API endpoints and HTTP operations you wish to include in your SDKs.
+1. Select **Generate API client**.
+    1. Enter configuration details about the SDK name, namespace, and output directory.
+    1. Select the language for the generated SDK.
+    
+        :::image type="content" source="media/discover-apis-vscode-extension/generate-api-client.png" alt-text="Screenshot of Kiota OpenAPI Explorer in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/generate-api-client.png":::
+    
+The client is generated.
+
+For details on using the Kiota extension, see [Microsoft Kiota extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-graph.kiota).
+
+## Export API specification
+
+You can export an API specification from a definition and then download it as a file.
+
+To export a specification in the extension's tree view:
+
+1. Expand the API Center tree view to show an API definition.    
+1. Right-click on the definition, and select **Export API Specification Document**. A new tab appears that renders an API specification document.
+
+    :::image type="content" source="media/discover-apis-vscode-extension/export-specification.png" alt-text="Screenshot of exporting API specification in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/export-specification.png":::
+
+You can also export a specification using the Command Palette:
+
+1. Type the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. 
+1. Select **Azure API Center: Export API Specification Document**.
+1. Make selections to navigate to an API definition. A new tab appears that renders an API specification document.
+
+## Related content
+
+* [Azure API Center - key concepts](key-concepts.md)
+* [Build and register APIs with the Azure API Center extension for Visual Studio Code](build-register-apis-vscode-extension.md)
+* [Govern APIs with the Azure API Center extension for Visual Studio Code](govern-apis-vscode-extension.md)
+* [Enable and view platform API catalog in Visual Studio Code](enable-platform-api-catalog-vscode-extension.md)
+

articles/api-center/discover-apis-vscode-extension.md

@@ -14,6 +14,9 @@ ms.custom:
 
 This article shows how to provide enterprise developers access to the Azure API Center platform API catalog (preview) in the Visual Studio Code extension for [Azure API Center](overview.md). Using the platform API catalog, developers can discover APIs in your Azure API center, view API definitions, and optionally generate API clients when they don't have access to manage the API center itself or add APIs to the inventory. Access to the platform API catalog is managed using Microsoft Entra ID and Azure role-based access control.
 
+> [!TIP]
+> The Visual Studio Code extension provides more features for API developers who have permissions to manage an Azure API center. For example, API developers can register APIs in the API center directly or using CI/CD pipelines. [Learn more](build-register-apis-vscode-extension.md) 
+
 ## Prerequisites
 
 ### For API center administrators

articles/api-center/enable-platform-api-catalog-vscode-extension.md

@@ -0,0 +1,61 @@
+---
+title: Govern APIs - VS Code extension
+description: API developers can use the Azure API Center extension for Visual Studio Code to govern their organization's APIs.
+author: dlepow
+ms.service: azure-api-center
+ms.topic: how-to
+ms.date: 10/16/2024
+ms.author: danlep 
+ms.custom: 
+# Customer intent: As an API developer, I want to use my Visual Studio Code environment to check API compliance in my organization's API center.
+---
+
+# Govern APIs with the Azure API Center extension for Visual Studio Code
+
+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](build-register-apis-vscode-extension.md) in the API center and [discover and consume APIs](discover-apis-vscode-extension.md).
+
+[!INCLUDE [vscode-extension-basic-prerequisites](includes/vscode-extension-basic-prerequisites.md)]  
+
+* [Spectral extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral) - to run shift-left API design conformance checks in Visual Studio Code
+* [Optic CLI](https://github.com/opticdev/optic) - to detect breaking changes between API specification documents
+
+[!INCLUDE [vscode-extension-setup](includes/vscode-extension-setup.md)]  
+
+## API design conformance
+
+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](https://stoplight.io/open-source/spectral).
+
+1. Use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. Type **Azure API Center: Set active API Style Guide** and hit **Enter**.
+2. 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":::
+
+## Breaking change detection
+
+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](https://github.com/opticdev/optic).
+
+1. Use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. Type **Azure API Center: Detect Breaking Change** and hit **Enter**.
+2. 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.
+3. 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":::
+
+
+## Related content
+
+* [Azure API Center - key concepts](key-concepts.md)
+* [Build and register APIs with the Azure API Center extension for Visual Studio Code](build-register-apis-vscode-extension.md)
+* [Discover and consume APIs with the Azure API Center extension for Visual Studio Code](discover-apis-vscode-extension.md)
+* [Enable and view platform API catalog in Visual Studio Code](enable-platform-api-catalog-vscode-extension.md)
+

articles/api-center/govern-apis-vscode-extension.md

@@ -0,0 +1,22 @@
+---
+title: Include file
+description: Include file
+services: api-center
+author: dlepow
+
+ms.service: azure-api-center
+ms.topic: include
+ms.date: 10/02/2024
+ms.author: danlep
+ms.custom: Include file
+---
+
+## Prerequisites
+
+* One or more API centers in your Azure subscription. 
+
+    * Currently, you need to be assigned the Contributor role or higher permissions to manage APIs with the extension.
+
+* [Visual Studio Code](https://code.visualstudio.com/)
+    
+* [Azure API Center extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=apidev.azure-api-center)

articles/api-center/includes/media/vscode-extension-setup/api-center-activity-bar.png

@@ -0,0 +1,24 @@
+---
+title: Include file
+description: Include file
+services: api-center
+author: dlepow
+
+ms.service: azure-api-center
+ms.topic: include
+ms.date: 10/02/2024
+ms.author: danlep
+ms.custom: Include file
+---
+
+## Setup
+
+1. Install the Azure API Center extension for Visual Studio Code from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=apidev.azure-api-center). Install other extensions as needed.
+
+    > [!NOTE]
+    > Where noted, certain features are available only in the Azure API Center extension's pre-release version. [!INCLUDE [vscode-extension-prerelease-features](vscode-extension-prerelease-features.md)]
+1. In Visual Studio Code, in the Activity Bar on the left, select API Center.
+
+    :::image type="content" source="media/vscode-extension-setup/api-center-activity-bar.png" alt-text="Screenshot of API Center extension in the activity bar.":::
+1. If you're not signed in to your Azure account, select **Sign in to Azure...**, and follow the prompts to sign in. 
+    Select an Azure subscription with the API center (or API centers) you wish to view APIs from. You can also filter on specific subscriptions if you have many to view from.