From 15246dcb07f5ea966cd16cc12717b66042cab70d Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 15:10:30 +0000 Subject: [PATCH 1/2] docs: document OpenAPI spec auth-gating and path-based multi-API URLs Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../docs/pages/developer-tools/openapi-spec.mdx | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/developer-tools/openapi-spec.mdx b/fern/products/docs/pages/developer-tools/openapi-spec.mdx index 64ec129515..0e03ebed3d 100644 --- a/fern/products/docs/pages/developer-tools/openapi-spec.mdx +++ b/fern/products/docs/pages/developer-tools/openapi-spec.mdx @@ -18,7 +18,7 @@ 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. Endpoints and API references marked `hidden: true` are excluded. 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. ## Usage @@ -38,3 +38,14 @@ If your docs site includes multiple API definitions, the endpoint returns a list # Get a specific API's spec curl https://your-docs-site.com/openapi.json?api=my-api-id ``` + +The path-based form serves a specific API's spec directly and is the recommended, CDN-friendly option: + +```bash +# Get a specific API's spec by path +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. A `?title=` query parameter also selects an API by normalized title match. + +If your docs site has password or SSO authentication configured, the spec endpoints inherit that authentication and return `401` to unauthenticated requests. There is no separate public toggle for the spec. From e8f98a47599c2140686c1ca536485a069533bd86 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 20 Jul 2026 14:35:05 -0400 Subject: [PATCH 2/2] condense info --- .../pages/developer-tools/openapi-spec.mdx | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/fern/products/docs/pages/developer-tools/openapi-spec.mdx b/fern/products/docs/pages/developer-tools/openapi-spec.mdx index 0e03ebed3d..635475b660 100644 --- a/fern/products/docs/pages/developer-tools/openapi-spec.mdx +++ b/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 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. Endpoints and API references marked `hidden: true` are excluded. 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. + + + Endpoints and API references marked `hidden: true` are excluded. + ## Usage @@ -32,20 +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: - -```bash -# Get a specific API's spec -curl https://your-docs-site.com/openapi.json?api=my-api-id -``` - -The path-based form serves a specific API's spec directly and is the recommended, CDN-friendly option: +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 by path 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. A `?title=` query parameter also selects an API by normalized title match. +The `my-api-id` segment resolves against an API's slug, title, or UUID. -If your docs site has password or SSO authentication configured, the spec endpoints inherit that authentication and return `401` to unauthenticated requests. There is no separate public toggle for the spec. + + If your docs site has password or SSO authentication configured, the spec endpoints inherit that authentication and return `401` to unauthenticated requests. +