Merge pull request #4 from aahill/openapi-spec

edits to openAPI doc

Author: lindazqli

articles/ai-services/agents/how-to/tools/openapi-spec.md

@@ -6,7 +6,7 @@ services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
 ms.topic: how-to
-ms.date: 12/16/2024
+ms.date: 03/12/2025
 author: aahill
 ms.author: aahi
 zone_pivot_groups: selection-function-calling
@@ -25,7 +25,7 @@ OpenAPI Specified tool improves your function calling experience by providing st
 automated, and scalable API integrations that enhance the capabilities and efficiency of your agent. 
 [OpenAPI specifications](https://spec.openapis.org/oas/latest.html) provide a formal standard for 
 describing HTTP APIs. This allows people to understand how an API works, how a sequence of APIs 
-work together, generate client code, create tests, apply design standards, and more. Currently, we support 3 authentication types with the OpenAPI 3.0 specified tools: `anonymous`, `API key`, `managed identity`.
+work together, generate client code, create tests, apply design standards, and more. Currently, we support three authentication types with the OpenAPI 3.0 specified tools: `anonymous`, `API key`, `managed identity`.
 
 ### Usage support
 
@@ -41,27 +41,29 @@ work together, generate client code, create tests, apply design standards, and m
 
 ## Authenticating with API Key
 
-With API key authentication type, you can authenticate your OpenAPI spec with various methods such as API key, Bearer token. Please note only one API key security schema is supported per OpenAPI spec. If you need multiple security schemas, please create multiple OpenAPI spec tools.
+With API key authentication, you can authenticate your OpenAPI spec using various methods such as an API key or Bearer token. Only one API key security schema is supported per OpenAPI spec. If you need multiple security schemas, create multiple OpenAPI spec tools.
+
+1. Update your OpenAPI spec security schemas. it has a `securitySchemes` section and one scheme of type `apiKey`. For example:
 
-1. Update your OpenAPI spec security schemes: it has `securitySchemes` section and has one scheme of type `apiKey`. For example:
    ```json
-       "securitySchemes": {
-          "apiKeyHeader": {
-                    "type": "apiKey",
-                    "name": "x-api-key",
-                    "in": "header"
-                }
-        }
+    "securitySchemes": {
+        "apiKeyHeader": {
+                "type": "apiKey",
+                "name": "x-api-key",
+                "in": "header"
+            }
+    }
    ```
+
    You usually only need to update the `name` field, which corresponds to the name of `key` in the connection. If the security schemes include multiple schemes, we recommend keeping only one of them.
 
-1. Update your OpenAPI spec to include `security` section:
+1. Update your OpenAPI spec to include a `security` section:
    ```json
    "security": [
-          {  
-            "apiKeyHeader": []  
-          }  
-        ]
+        {  
+        "apiKeyHeader": []  
+        }  
+    ]
    ```
 
 1. Remove any parameter in the OpenAPI spec that needs API key, because API key will be stored and passed through a connection, as described later in this article.
@@ -96,31 +98,37 @@ With API key authentication type, you can authenticate your OpenAPI spec with va
       - Connection name: YOUR_CONNECTION_NAME (You will use this connection name in the sample code below.)
       - Access: you can choose either *this project only* or *shared to all projects*. Just make sure in the sample code below, the project you entered connection string for has access to this connection.
 
-1. Once you have created a connection, you can use it through SDK or REST API. Please use the tabs above to navigate to your preferred ways of usage.
+1. Once you have created a connection, you can use it through the SDK or REST API. Use the tabs at the top of this article to see code examples.
 
-## Authenticating with Managed Identity (Microsoft Entra ID)
-[Managed Identity (Microsoft Entra ID)](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) is a cloud-based identity and access management service that your employees can use to access external resources. Microsoft Entra ID allows you to authenticate your APIs with additional security without the need to pass in API keys. Once you have set up Managed Identity authentication, it will authenticate through the Azure AI Service your agent is using. 
+## Authenticating with managed identity (Microsoft Entra ID)
+
+[Microsoft Entra ID](/entra/fundamentals/whatis) is a cloud-based identity and access management service that your employees can use to access external resources. Microsoft Entra ID allows you to authenticate your APIs with additional security without the need to pass in API keys. Once you have set up managed identity authentication, it will authenticate through the Azure AI Service your agent is using. 
 
 To set up authenticating with Managed Identity:
+
 1. Enable the Azure AI Service of your agent has `system assigned managed identity` enabled.
-   ![image](https://github.com/user-attachments/assets/55e3125c-ca97-43e7-80ef-d8f3cc005fe4)
 
-1. Create a resource of the service you want to connect to through OpenAPI spec
+    :::image type="content" source="../../media/tools/managed-identity-portal.png" alt-text="A screenshot showing the managed identity selector in the Azure portal." lightbox="../../media/tools/managed-identity-portal.png":::
+
+1. Create a resource of the service you want to connect to through OpenAPI spec.
 
-1. Assign Azure AI Service proper access to the resource
-    1. Click "Access Control" of your resource
+1. Assign proper access to the resource.
+    1. Click **Access Control** for your resource
 
-    1. Click "Add" and then "add role assignement" on the top
+    1. Click **Add** and then **add role assignment** at the top of the screen.
+
+        :::image type="content" source="../../media/tools/role-assignment-portal.png" alt-text="A screenshot showing the role assignment selector in the Azure portal." lightbox="../../media/tools/role-assignment-portal.png":::
+        
+    1. Select the proper role assignment needed, usually it will require at least *READER* role. Then click **Next**.
 
-    1. Select the proper role assignment needed, usually it will require at least READER role. Then click "Next"
+    1. Select **Managed identity** and then click **select members**.
 
-    1. Select "Managed identity" and then click "select members"
+    1. In the managed identity dropdown menu, search for **Azure AI services** and then select the AI Service of your agent.
 
-    1. In the Managed Identity dropdown, search for "Azure AI services" and then select the AI Service of your agent.
+    1. Click **Finish**.
 
-    1. Click "Finish"
+1. Once the setup is done, you can continue by using the tool through the SDK or REST API. Use the tabs at the top of this article to see code samples.
 
-1. Once you have it set up, you can use continue creating the tool through SDK or REST API. Please use the tabs above to navigate to your preferred ways of usage.
 ::: zone-end