Remaining feedback

docs/docs/how-tos/auth/openapi_security.md

@@ -1,8 +1,11 @@
 # How to document API authentication in OpenAPI
 
-This guide shows how to customize the OpenAPI security schema for your LangGraph Platform API documentation. This only updates the OpenAPI specification to document your security requirements - to implement the actual authentication logic, see [How to add custom authentication](./custom_auth.md).
+This guide shows how to customize the OpenAPI security schema for your LangGraph Platform API documentation. A well-documented security schema helps API consumers understand how to authenticate with your API and even enables automatic client generation. See the [Authentication & Access Control conceptual guide](../../concepts/auth.md) for more details about LangGraph's authentication system.
 
-This guide applies to all LangGraph Platform deployments (Cloud, BYOC, and self-hosted). It does not apply to isolated usage of the LangGraph open source library in your own custom server.
+!!! note "Implementation vs Documentation"
+    This guide only covers how to document your security requirements in OpenAPI. To implement the actual authentication logic, see [How to add custom authentication](./custom_auth.md).
+
+This guide applies to all LangGraph Platform deployments (Cloud, BYOC, and self-hosted). It does not apply to usage of the LangGraph open source library if you are not using LangGraph Platform.
 
 ## Default Schema
 
@@ -37,54 +40,54 @@ Note that LangGraph Platform does not provide authentication endpoints - you'll
 
 === "OAuth2 with Bearer Token"
 
-```json
-{
-  "auth": {
-    "path": "./auth.py:my_auth",  // Implement auth logic here
-    "openapi": {
-      "securitySchemes": {
-        "OAuth2": {
-          "type": "oauth2",
-          "flows": {
-            "implicit": {
-              "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
-              "scopes": {
-                "me": "Read information about the current user",
-                "threads": "Access to create and manage threads"
+    ```json
+    {
+      "auth": {
+        "path": "./auth.py:my_auth",  // Implement auth logic here
+        "openapi": {
+          "securitySchemes": {
+            "OAuth2": {
+              "type": "oauth2",
+              "flows": {
+                "implicit": {
+                  "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
+                  "scopes": {
+                    "me": "Read information about the current user",
+                    "threads": "Access to create and manage threads"
+                  }
+                }
               }
             }
-          }
+          },
+          "security": [
+            {"OAuth2": ["me", "threads"]}
+          ]
         }
-      },
-      "security": [
-        {"OAuth2": ["me", "threads"]}
-      ]
+      }
     }
-  }
-}
-```
+    ```
 
 === "API Key"
 
-```json
-{
-  "auth": {
-    "path": "./auth.py:my_auth",  // Implement auth logic here
-    "openapi": {
-      "securitySchemes": {
-        "apiKeyAuth": {
-          "type": "apiKey",
-          "in": "header",
-          "name": "X-API-Key"
+    ```json
+    {
+      "auth": {
+        "path": "./auth.py:my_auth",  // Implement auth logic here
+        "openapi": {
+          "securitySchemes": {
+            "apiKeyAuth": {
+              "type": "apiKey",
+              "in": "header",
+              "name": "X-API-Key"
+            }
+          },
+          "security": [
+            {"apiKeyAuth": []}
+          ]
         }
-      },
-      "security": [
-        {"apiKeyAuth": []}
-      ]
+      }
     }
-  }
-}
-```
+    ```
 
 ## Testing