docs: document OpenAPI spec auth-gating and path-based multi-API URLs (#6319)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Devin Logan <devinannlogan@gmail.com>

Author: devin-ai-integration[bot]

fern/products/docs/pages/developer-tools/openapi-spec.mdx

@@ -18,7 +18,11 @@ Every Fern docs site exposes the OpenAPI specification at these paths:
 | `/openapi.yaml` | YAML | `application/x-yaml` |
 | `/openapi.yml` | YAML | `application/x-yaml` |
 
-The spec includes all endpoints with request/response schemas, authentication schemes (Bearer, Basic, API Key, OAuth), webhooks, type definitions as component schemas, and server URLs from your environment configuration. The [`info.version`](/learn/api-definitions/openapi/extensions/api-version) field from your source spec is preserved as-is, including non-SemVer formats like CalVer. The spec is generated from the same API definition that powers your docs, so it's always up to date.
+The spec includes your endpoints with request/response schemas, authentication schemes (Bearer, Basic, API Key, OAuth), webhooks, type definitions as component schemas, and server URLs from your environment configuration. The [`info.version`](/learn/api-definitions/openapi/extensions/api-version) field from your source spec is preserved as-is, including non-SemVer formats like CalVer. The spec is generated from the same API definition that powers your docs, so it's always up to date.
+
+<Info>
+    Endpoints and API references marked `hidden: true` are excluded.
+</Info>
 
 ## Usage
 
@@ -32,9 +36,14 @@ curl https://your-docs-site.com/openapi.json
 curl https://your-docs-site.com/openapi.yaml
 ```
 
-If your docs site includes multiple API definitions, the endpoint returns a listing of available APIs. Use the `api` query parameter to select a specific one:
+If your docs site includes multiple API definitions, the endpoint returns a listing of available APIs. To select a specific one, use the path-based form, which serves the spec directly and is CDN-friendly:
 
 ```bash
-# Get a specific API's spec
-curl https://your-docs-site.com/openapi.json?api=my-api-id
+curl https://your-docs-site.com/openapi/my-api-id.json
 ```
+
+The `my-api-id` segment resolves against an API's slug, title, or UUID.
+
+<Note>
+    If your docs site has password or SSO authentication configured, the spec endpoints inherit that authentication and return `401` to unauthenticated requests.
+</Note>