Merge pull request #291465 from MicrosoftDocs/main

12/5 11:00 AM IST Publish

Author: PhilKang0704

articles/api-center/enable-api-analysis-linting.md

@@ -3,7 +3,7 @@ title: Perform API linting and analysis - Azure API Center
 description: Configure linting of API definitions in your API center to analyze compliance of APIs with the organization's API style guide.
 ms.service: azure-api-center
 ms.topic: how-to
-ms.date: 06/29/2024
+ms.date: 12/03/2024
 ms.author: danlep
 author: dlepow
 ms.custom: devx-track-azurecli
@@ -12,10 +12,10 @@ ms.custom: devx-track-azurecli
 
 # Enable API analysis in your API center - self-managed
 
-This article explains how to enable API analysis in [Azure API Center](overview.md) by manually setting up a linting engine and triggers. API analysis offers linting capabilities to analyze API definitions in your organization's API center. Linting ensures your API definitions adhere to organizational style rules, generating both individual and summary reports. Use API analysis to identify and correct common errors and inconsistencies in your API definitions.
+This article explains how to enable API analysis in [Azure API Center](overview.md) by manually setting up a linting engine and triggers. These capabilities analyze your API definitions for adherence to organizational style rules, generating both individual and summary reports. API analysis helps identify and correct common errors and inconsistencies in your API definitions.
 
 > [!NOTE]
-> In preview, Azure API Center can also automatically set up a linting engine and any required dependencies and triggers. [Learn more](enable-managed-api-analysis-linting.md). 
+> In preview, Azure API Center [automatically configures](enable-managed-api-analysis-linting.md) a default linting engine and dependencies for API analysis. If you enable self-managed analysis as described in this article, you override these built-in features.  
 
 > [!VIDEO https://www.youtube.com/embed/m0XATQaVhxA]
 

articles/api-center/enable-managed-api-analysis-linting.md

@@ -1,71 +1,48 @@
 ---
 title: Managed API linting and analysis - Azure API Center
-description: Enable managed linting of API definitions in your API center to analyze compliance of APIs with the organization's API style guide.
+description: Automatic linting of API definitions in your API center helps you analyze compliance of APIs with the organization's API style guide.
 ms.service: azure-api-center
 ms.topic: how-to
-ms.date: 11/01/2024
+ms.date: 12/03/2024
 ms.author: danlep
 author: dlepow
 ms.custom: 
 # Customer intent: As an API developer or API program manager, I want to analyze the API definitions in my organization's API center for compliance with my organization's API style guide.
 ---
 
-# Enable API analysis in your API center - Microsoft managed
+# Analyze APIs in your API center - Microsoft managed
 
-This article explains how to enable API analysis in [Azure API Center](overview.md) without having to manage it yourself (preview). API analysis offers linting capabilities to analyze API definitions in your organization's API center. Linting ensures your API definitions adhere to organizational style rules, generating both individual and summary reports. Use API analysis to identify and correct common errors and inconsistencies in your API definitions.
+Your organization's [API center](overview.md) includes built-in, Microsoft-managed linting capabilities (preview) to analyze API definitions for adherence to organizational style rules, generating both individual and summary reports. API analysis identifies and helps you correct common errors and inconsistencies in your API definitions.
 
-> [!IMPORTANT]
-> Managed API analysis in API Center sets up a linting engine and necessary dependencies automatically. You can also enable linting and analysis [manually](enable-api-analysis-linting.md) using a custom Azure function. **Disable any function used for manual linting before enabling managed API analysis.**
+With API analysis:
 
+* Azure API Center automatically analyzes your API definitions whenever you add or update an API definition. API definitions are linted by default with a [spectral:oas ruleset](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules) (API style guide).  
+* API analysis reports are generated in the Azure portal, showing how your API definitions conform to the style guide.
+* You can use the Azure API Center extension for Visual Studio Code to customize and test your own API style guide locally and then deploy it to your API center. 
 
-In this scenario:
 
-1. Add a linting ruleset (API style guide) in your API center using the Visual Studio Code extension for Azure API Center.
-1. Azure API Center automatically runs linting when you add or update an API definition. It's also triggered for all API definitions when you deploy a ruleset to your API center.
-1. Review API analysis reports in the Azure portal to see how your API definitions conform to the style guide.
-1. Optionally customize the ruleset for your organization's APIs. Test the custom ruleset locally before deploying it to your API center. 
+> [!IMPORTANT]
+> If you prefer, you can enable [self-managed](enable-api-analysis-linting.md) linting and analysis using a custom Azure function, overriding the built-in capabilities. **Disable any function used for self-managed linting before using managed API analysis.**
 
 ## Limitations
 
-* Currently, only OpenAPI specification documents in JSON or YAML format are analyzed.
-* By default, you enable analysis with the [`spectral:oas` ruleset](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules). To learn more about the built-in rules, see the [Spectral GitHub repo](https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md). 
+* Currently, only OpenAPI and AsyncAPI specification documents in JSON or YAML format are analyzed.
 * Currently, you configure a single ruleset, and it's applied to all OpenAPI definitions in your API center.
 * There are [limits](../azure-resource-manager/management/azure-subscription-service-limits.md?toc=/azure/api-center/toc.json&bc=/azure/api-center/breadcrumb/toc.json#api-center-limits) for the maximum number of API definitions analyzed. Analysis can take a few minutes to up to 24 hours to complete.
 
 ## Prerequisites
 
-* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
-* [Visual Studio Code](https://code.visualstudio.com/) 
-
-* The following Visual Studio Code extensions:
+* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md). 
+* For customizing the ruleset, [Visual Studio Code](https://code.visualstudio.com/) and the following Visual Studio Code extensions:
     * [Azure API Center extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=apidev.azure-api-center)
-
-        > [!IMPORTANT]
-        > Enable managed API analysis using the API Center extension's pre-release version. When installing the extension, choose the pre-release version. Switch between release and pre-release versions any time via the extension's **Manage** button in the Extensions view.
     * [Spectral extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)
 
-## Enable API analysis using Visual Studio Code
-
-To enable API analysis using the default linting ruleset:
-
-1. In Visual Studio Code, open a folder that you'll use to manage rulesets for Azure API Center.
-1. Select the Azure API Center icon from the Activity Bar.
-1. In the API Center pane, expand the API center resource in which to enable API analysis.
-1. Right-click **Rules** and select **Enable API Analysis**.
-
-    :::image type="content" source="media/enable-managed-api-analysis-linting/enable-analysis-visual-studio-code.png" alt-text="Screenshot of enabling API linting and analysis in Visual Studio Code.":::
-
-A message notifies you after API analysis is successfully enabled. A folder for your API center is created in `.api-center-rules`, at the root of your working folder. The folder for your API center contains:
- 
-* A `ruleset.yml` file that defines the default API style guide used by the linting engine.
-* A `functions` folder with an example custom function that you can use to extend the ruleset. 
-
-With analysis enabled, the linting engine analyzes API definitions in your API center based on the default ruleset and generates API analysis reports.
-
 ## View API analysis reports
 
 View an analysis summary and the analysis reports for your API definitions in the Azure portal. After API definitions are analyzed, the reports list errors, warnings, and information based on the configured API style guide. 
 
+In the API analysis report, also review the ruleset that was used for the analysis and the history of linting passes.
+
 To view an analysis summary in your API center:
 
 1. In the portal, navigate to your API center.
@@ -82,12 +59,13 @@ To view an analysis summary in your API center:
 
 ## Customize ruleset
 
-You can customize the default ruleset or replace it as your organization's API style guide. For example, you can [extend the ruleset](https://docs.stoplight.io/docs/spectral/83527ef2dd8c0-extending-rulesets) or add [custom functions](https://docs.stoplight.io/docs/spectral/a781e290eb9f9-custom-functions).
+You can use the Azure API Center extension for Visual Studio Code to customize the default ruleset for your API center or replace it as your organization's API style guide. For example, you can [extend the ruleset](https://docs.stoplight.io/docs/spectral/83527ef2dd8c0-extending-rulesets) or add [custom functions](https://docs.stoplight.io/docs/spectral/a781e290eb9f9-custom-functions).
 
 To customize or replace the ruleset:
 
-1. In Visual Studio Code, open the `.api-center-rules` folder at the root of your working folder.
-1. In the folder for the API center resource, open the `ruleset.yml` file.
+1. In Visual Studio Code, select the Azure API Center icon from the Activity Bar.
+1. Open the `.api-center-rules` folder at the root of your working folder.
+1. In the folder for your API center resource, open the `ruleset.yml` file.
 1. Modify or replace the content as needed. 
 1. Save your changes to `ruleset.yml`.
 
@@ -103,6 +81,9 @@ Before deploying the custom ruleset to your API center, validate it locally. The
 
 Now, when you open an OpenAPI-based API definition file, a local linting operation is automatically triggered in Visual Studio Code. Results are displayed inline in the editor and in the **Problems** window (**View > Problems** or **Ctrl+Shift+M**).
 
+> [!TIP]
+> API developers in your organization can also use this local linting capability to help improve their API definitions before registering APIs in your API center.
+
 :::image type="content" source="media/enable-managed-api-analysis-linting/validate-local-linting.png" alt-text="Screenshot of linting an API definition in Visual Studio Code." lightbox="media/enable-managed-api-analysis-linting/validate-local-linting.png":::
 
 Review the linting results. Make any necessary adjustments to the ruleset and continue to test it locally until it performs the way you want.
@@ -121,4 +102,5 @@ To see the results of linting with the updated ruleset, view the API analysis re
 
 ## Related content
 
+* To learn more about the default built-in ruleset, see the [Spectral GitHub repo](https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md). 
 * [Enable API analysis in your API center - self-managed](enable-api-analysis-linting.md)

articles/api-center/media/enable-api-analysis-linting/api-analysis-summary.png

@@ -12,7 +12,7 @@ ms.custom: devx-track-azurecli
 
 # Synchronize APIs from an API Management instance
 
-This article shows how to create a link (preview) to an API Management instance so that the instances's APIs are continuously kept up to date in your [API center](overview.md) inventory. 
+This article shows how to create a link to an API Management instance so that the instances's APIs are continuously kept up to date in your [API center](overview.md) inventory. 
 
 ## About linking an API Management instance
 

articles/api-center/synchronize-api-management-apis.md

@@ -23,7 +23,7 @@ API Management has the following immutable groups:
     > [!NOTE]
     > At any time, a service owner can update the administrator [email settings](api-management-howto-configure-notifications.md#configure-email-settings) that are used in notifications from your API Management instance.
 
-* **Developers** - Authenticated developer portal users fall into this group. Developers are the customers that build applications using your APIs. Developers are granted access to the developer portal and build applications that call the operations of an API.
+* **Developers** - Authenticated developer portal [users](api-management-howto-create-or-invite-developers.md) fall into this group. Developers are the customers that build applications using your APIs. Developers are granted access to the developer portal and build applications that call the operations of an API.
 * **Guests** - Unauthenticated developer portal users, such as prospective customers visiting the developer portal of an API Management instance fall into this group. They can be granted certain read-only access, such as the ability to view APIs but not call them.
 
 In addition to these system groups, administrators can create custom groups or [use external groups in associated Microsoft Entra tenants][leverage external groups in associated Azure Active Directory tenants]. Custom and external groups can be used alongside system groups in giving developers visibility and access to API products. For example, you could create one custom group for developers affiliated with a specific partner organization and allow them access to the APIs from a product containing relevant APIs only. A user can be a member of more than one group.