Merge pull request #287733 from MicrosoftDocs/main

Publish to Live Wednesday 4AM PST, 10/2

Author: PMEds28

.openpublishing.redirection.json

@@ -4769,7 +4769,7 @@
     },
     {
       "source_path_from_root": "/articles/third-party-notices.md",
-      "redirect_url": "/azure-docs/ThirdPartyNotices.md",
+      "redirect_url": "https://github.com/MicrosoftDocs/azure-docs/blob/main/ThirdPartyNotices.md",
       "redirect_document_id": false
     }
   ]

articles/api-center/.openpublishing.redirection.json

@@ -0,0 +1,10 @@
+{
+    "redirections": [
+        {
+            "source_path_from_root": "/articles/api-center/use-vscode-extension.md",
+            "redirect_url": "/azure/api-center/build-register-apis-vscode-extension",
+            "redirect_document_id": false
+        }
+
+    ]
+}

articles/api-center/TOC.yml

@@ -38,8 +38,8 @@
         href: manage-apis-azure-cli.md
       - name: Import APIs from API Management
         href: import-api-management-apis.md
-      - name: Register APIs - VS Code extension
-        href: use-vscode-extension.md
+      - name: Build and register APIs - VS Code extension
+        href: build-register-apis-vscode-extension.md
       - name: Register APIs - GitHub Actions
         href: register-apis-github-actions.md
 - name: API governance
@@ -56,6 +56,8 @@
         href: find-nonproduction-api-requests-dev-proxy.md
 - name: API discovery and consumption
   items:
+      - name: Enable platform API catalog - VS Code extension
+        href: enable-platform-api-catalog-vscode-extension.md
       - name: Self-host Azure API Center portal
         href: enable-api-center-portal.md
       - name: Check API calls use minimal permissions with Dev Proxy

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

@@ -1,24 +1,24 @@
 ---
-title: Interact with API inventory using VS Code extension
-description: Build, discover, try, and consume APIs from your Azure API center using the Azure API Center extension for Visual Studio Code.
+title: Build and register APIs - Azure API Center - VS Code extension
+description: API developers can use the Azure API Center extension for Visual Studio Code to build and register APIs in their organization's API center.
 author: dlepow
 ms.service: azure-api-center
 ms.topic: how-to
-ms.date: 08/01/2024
+ms.date: 09/23/2024
 ms.author: danlep 
 ms.custom: 
-# Customer intent: As a developer, I want to use my Visual Studio Code environment to build, discover, try, and consume APIs in my organization's API center.
+# Customer intent: As an API developer, I want to use my Visual Studio Code environment to build, discover, explore, and consume APIs in my organization's API center.
 ---
 
-# Get started with the Azure API Center extension for Visual Studio Code
+# Build and register APIs with the Azure API Center extension for Visual Studio Code
 
-To build, discover, try, and consume APIs in your [API center](overview.md), you can use the Azure API Center extension in your Visual Studio Code development environment:
+To build, discover, explore, and consume APIs in your [API center](overview.md), you can use the Azure API Center extension in your Visual Studio Code development environment. The extension provides the following features for API developers:
 
-* **Build APIs** - Make APIs you're building discoverable to others by registering them in your API center. Shift-left API design conformance checks into Visual Studio Code with integrated linting support. Ensure that new API versions don't break API consumers with breaking change detection.
+* **Build APIs** - Make APIs you're building discoverable to others by registering them in your API center directly or using CI/CD pipelines in GitHub or Azure DevOps. Shift-left API design conformance checks into Visual Studio Code with integrated linting support. Ensure that new API versions don't break API consumers with breaking change detection.
 
 * **Discover APIs** - Browse the APIs in your API center, and view their details and documentation.
 
-* **Try APIs** - Use Swagger UI or REST client to explore API requests and responses. 
+* **Explore APIs** - Use Swagger UI or REST client to explore API requests and responses. 
 
 * **Consume APIs** - Generate API SDK clients for your favorite language including JavaScript, TypeScript, .NET, Python, and Java, using the Microsoft Kiota engine that generates SDKs for Microsoft Graph, GitHub, and more. 
 
@@ -28,14 +28,14 @@ To build, discover, try, and consume APIs in your [API center](overview.md), you
 
 * One or more API centers in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
 
-    Currently, you need to be assigned the Contributor role or higher permissions to access API centers with the extension.
+    Currently, you need to be assigned the Contributor role or higher permissions to manage API centers 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)
 
     > [!NOTE]
-    > Where noted, certain features are available only in the extension's pre-release version. When installing the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=apidev.azure-api-center&ssr=false#overview), you can choose to install the release version or a pre-release version. Switch between the two versions at any time by using the extension's **Manage** button context menu in the Extensions view. 
+    > Where noted, certain features are available only in the extension's pre-release version. [!INCLUDE [vscode-extension-prerelease-features](includes/vscode-extension-prerelease-features.md)]
     
 The following Visual Studio Code extensions are optional and needed only for certain scenarios as indicated:
 
@@ -64,6 +64,9 @@ Register an API in your API center directly from Visual Studio Code, either by r
     * For **Step-by-step**, select the API center to register APIs with, and answer prompts with information including API title, type, lifecycle stage, version, and specification to complete API registration.
     * For **CI/CD**, select either **GitHub** or **Azure DevOps**, depending on your preferred source control mechanism. A Visual Studio Code workspace must be open for the Azure API Center extension to add a pipeline to your workspace. After the file is added, complete steps documented in the CI/CD pipeline file itself to configure Azure Pipeline/GitHub Action environment variables and identity. On push to source control, the API will be registered in your API center.
 
+    Learn more about setting up a [GitHub Actions workflow](register-apis-github-actions.md) to register APIs with your API center.
+
+
 ## 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.
@@ -73,7 +76,7 @@ To ensure design conformance with organizational standards as you build APIs, th
 
 Once an active API style guide is set, opening any OpenAPI or AsyncAPI-based specification file will trigger a local linting operation in Visual Studio Code. Results are displayed both inline in the editor, as well as in the Problems window (**View** > **Problems** or **Ctrl+Shift+M**).
 
-:::image type="content" source="media/use-vscode-extension/local-linting.png" alt-text="Screenshot of local-linting in Visual Studio Code." lightbox="media/use-vscode-extension/local-linting.png":::
+:::image type="content" source="media/build-register-apis-vscode-extension/local-linting.png" alt-text="Screenshot of local-linting in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/local-linting.png":::
 
 ## Breaking change detection
 
@@ -85,7 +88,7 @@ When introducing new versions of your API, it's important to ensure that changes
 
 Visual Studio Code will open a diff view between the two API specifications. Any breaking changes are displayed both inline in the editor, as well as in the Problems window (**View** > **Problems** or **Ctrl+Shift+M**).
 
-:::image type="content" source="media/use-vscode-extension/breaking-changes.png" alt-text="Screenshot of breaking changes detected in Visual Studio Code." lightbox="media/use-vscode-extension/breaking-changes.png":::
+:::image type="content" source="media/build-register-apis-vscode-extension/breaking-changes.png" alt-text="Screenshot of breaking changes detected in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/breaking-changes.png":::
 
 ## Generate OpenAPI specification file from API code 
 
@@ -94,26 +97,29 @@ Use the power of GitHub Copilot with the Azure API Center extension for Visual S
 > [!NOTE]
 > This feature is available in the pre-release version of the API Center extension.
 
-:::image type="content" source="media/use-vscode-extension/generate-api-documentation.gif" alt-text="Animation showing how to use GitHub Copilot to generate an OpenAPI spec from code." lightbox="media/use-vscode-extension/generate-api-documentation.gif":::
+:::image type="content" source="media/build-register-apis-vscode-extension/generate-api-documentation.gif" alt-text="Animation showing how to use GitHub Copilot to generate an OpenAPI spec from code." lightbox="media/build-register-apis-vscode-extension/generate-api-documentation.gif":::
 
 After generating the OpenAPI specification file and checking for accuracy, you can register the API with your API center using the **Azure API Center: Register API** command.
 
 ## Discover APIs
 
 Your 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/use-vscode-extension/explore-api-centers.png" alt-text="Screenshot of API Center tree view in Visual Studio Code." lightbox="media/use-vscode-extension/explore-api-centers.png":::
+:::image type="content" source="media/build-register-apis-vscode-extension/explore-api-centers.png" alt-text="Screenshot of API Center tree view in Visual Studio Code." lightbox="media/build-register-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.
 
+> [!TIP]
+> Optionally enable a [platform API catalog](enable-platform-api-catalog-vscode-extension.md) for your API center in Visual Studio Code so that app developers in your organization can discover APIs in a centralized location. The platform API catalog is a read-only view of the API inventory.
+
 ## 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/use-vscode-extension/view-api-documentation.png" alt-text="Screenshot of API documentation in Visual Studio Code." lightbox="media/use-vscode-extension/view-api-documentation.png":::
+    :::image type="content" source="media/build-register-apis-vscode-extension/view-api-documentation.png" alt-text="Screenshot of API documentation in Visual Studio Code." lightbox="media/build-register-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**.
 
@@ -130,7 +136,7 @@ You can view a `.http` file based on the API definition in your API center. If t
 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/use-vscode-extension/generate-http-file.png" alt-text="Screenshot of generating a .http file in Visual Studio Code." lightbox="media/use-vscode-extension/generate-http-file.png":::
+    :::image type="content" source="media/build-register-apis-vscode-extension/generate-http-file.png" alt-text="Screenshot of generating a .http file in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/generate-http-file.png":::
 
 1. To make a request, select an endpoint, and select **Send Request**.
 
@@ -148,7 +154,7 @@ Use the Microsoft Kiota extension to generate an API client for your favorite la
     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/use-vscode-extension/generate-api-client.png" alt-text="Screenshot of Kiota OpenAPI Explorer in Visual Studio Code." lightbox="media/use-vscode-extension/generate-api-client.png":::
+        :::image type="content" source="media/build-register-apis-vscode-extension/generate-api-client.png" alt-text="Screenshot of Kiota OpenAPI Explorer in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/generate-api-client.png":::
 
 The client is generated.
 
@@ -163,7 +169,7 @@ 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/use-vscode-extension/export-specification.png" alt-text="Screenshot of exporting API specification in Visual Studio Code." lightbox="media/use-vscode-extension/export-specification.png":::
+    :::image type="content" source="media/build-register-apis-vscode-extension/export-specification.png" alt-text="Screenshot of exporting API specification in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/export-specification.png":::
 
 You can also export a specification using the Command Palette:
 
@@ -174,4 +180,5 @@ You can also export a specification using the Command Palette:
 ## Related content
 
 * [Azure API Center - key concepts](key-concepts.md)
+* [Enable and view platform API catalog in Visual Studio Code](enable-platform-api-catalog-vscode-extension.md)