Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(api): carry endpoint deprecation notices into the API reference (#16121)

Niklas Semmlerb3283dccc595
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4ae80117fe..0328612efc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -541,7 +541,7 @@ To export the respective `openapi.yml` files which power the online API referenc
pnpm run openapi:export
```
-This command also syncs standard OpenAPI `deprecated` flags from the endpoint `availability` metadata in the Fern definitions.
+This command also syncs standard OpenAPI `deprecated` flags and `**Deprecated:** …` description notices from the endpoint `availability` metadata in the Fern definitions.
To generate the server SDKs, run:
diff --git a/fern/apis/server/definition/dataset-run-items.yml b/fern/apis/server/definition/dataset-run-items.yml
index cc3045770f..d5dc71e2b0 100644
--- a/fern/apis/server/definition/dataset-run-items.yml
+++ b/fern/apis/server/definition/dataset-run-items.yml
@@ -18,7 +18,7 @@ service:
list:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, dataset run items are replaced by experiment items; use GET /api/public/experiment-items?fromStartTime=<from>&toStartTime=<to> instead."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, dataset run items are replaced by experiment items; use `GET /api/public/experiment-items?fromStartTime=<from>&toStartTime=<to>` instead."
method: GET
docs: List dataset run items
path: /dataset-run-items
diff --git a/fern/apis/server/definition/ingestion.yml b/fern/apis/server/definition/ingestion.yml
index 5c194bcb90..9b3846bd4f 100644
--- a/fern/apis/server/definition/ingestion.yml
+++ b/fern/apis/server/definition/ingestion.yml
@@ -9,7 +9,7 @@ service:
batch:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Send data via the OpenTelemetry endpoint at POST /api/public/otel/v1/traces instead. Learn more: https://langfuse.com/integrations/native/opentelemetry"
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Send data via the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` instead, see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry)."
docs: |
**Legacy endpoint for batch ingestion for Langfuse Observability.**
diff --git a/fern/apis/server/definition/legacy/metrics-v1.yml b/fern/apis/server/definition/legacy/metrics-v1.yml
index e41a2e54b6..1b526275b5 100644
--- a/fern/apis/server/definition/legacy/metrics-v1.yml
+++ b/fern/apis/server/definition/legacy/metrics-v1.yml
@@ -9,7 +9,7 @@ service:
metrics:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use GET /api/public/v2/metrics?query=<urlencoded json query> instead."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use `GET /api/public/v2/metrics?query=<urlencoded json query>` instead."
docs: |
Get metrics from the Langfuse project using a query object.
diff --git a/fern/apis/server/definition/legacy/observations-v1.yml b/fern/apis/server/definition/legacy/observations-v1.yml
index 0e63d68098..c77d1d86a4 100644
--- a/fern/apis/server/definition/legacy/observations-v1.yml
+++ b/fern/apis/server/definition/legacy/observations-v1.yml
@@ -9,7 +9,7 @@ service:
get:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to> instead."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>` instead."
docs: Get a observation
method: GET
path: /observations/{observationId}
@@ -21,7 +21,7 @@ service:
getMany:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to> instead."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>` instead."
docs: |
Get a list of observations.
diff --git a/fern/apis/server/definition/scores.yml b/fern/apis/server/definition/scores.yml
index 300a7cddd9..0f86d4aa29 100644
--- a/fern/apis/server/definition/scores.yml
+++ b/fern/apis/server/definition/scores.yml
@@ -15,12 +15,8 @@ service:
get-many:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use GET /api/public/v3/scores instead."
- docs: |
- **Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
- is no longer available on Langfuse v4 and later.
-
- Get a list of scores (supports both trace and session scores)
+ message: "Langfuse v3 is deprecated; this endpoint is not available on Langfuse v4 and later and will be removed in a future release. Use `GET /api/public/v3/scores` instead."
+ docs: Get a list of scores (supports both trace and session scores)
method: GET
path: /v2/scores
request:
@@ -100,12 +96,8 @@ service:
get-by-id:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. Use GET /api/public/v3/scores with the id filter instead."
- docs: |
- **Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
- instead. This endpoint is no longer available on Langfuse v4 and later.
-
- Get a score (supports both trace and session scores)
+ message: "Langfuse v3 is deprecated; this endpoint is not available on Langfuse v4 and later and will be removed in a future release. Use `GET /api/public/v3/scores` with the `id` filter instead."
+ docs: Get a score (supports both trace and session scores)
method: GET
path: /v2/scores/{scoreId}
path-parameters:
diff --git a/fern/apis/server/definition/sessions.yml b/fern/apis/server/definition/sessions.yml
index d42a0e9043..4b43c38dab 100644
--- a/fern/apis/server/definition/sessions.yml
+++ b/fern/apis/server/definition/sessions.yml
@@ -9,7 +9,7 @@ service:
list:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read session data via GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read session data via `GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>`."
docs: |
Get sessions.
@@ -42,7 +42,7 @@ service:
get:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read session data via GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read session data via `GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>`."
docs: |
Get a session.
diff --git a/fern/apis/server/definition/trace.yml b/fern/apis/server/definition/trace.yml
index 8e61c28115..ffcd383a84 100644
--- a/fern/apis/server/definition/trace.yml
+++ b/fern/apis/server/definition/trace.yml
@@ -9,7 +9,7 @@ service:
get:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read span and trace data via GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read span and trace data via `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`."
docs: Get a specific trace
method: GET
path: /traces/{traceId}
@@ -36,7 +36,7 @@ service:
list:
availability:
status: deprecated
- message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read span and trace data via GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>."
+ message: "Langfuse v3 is deprecated; this endpoint will be removed in a future release. In Langfuse v4, read span and trace data via `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`."
docs: Get list of traces
method: GET
path: /traces
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index dd5f1517e4..b7fc04a762 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -804,8 +804,7 @@ paths:
- name: objectType
in: query
description: >-
- Filter comments by object type (trace, observation, session,
- prompt).
+ Filter comments by object type (trace, observation, session, prompt).
required: false
schema:
type: string
@@ -1089,8 +1088,7 @@ paths:
security: *ref_0
delete:
description: >-
- Delete a dataset item and all its run items. This action is
- irreversible.
+ Delete a dataset item and all its run items. This action is irreversible.
operationId: datasetItems_delete
tags:
- DatasetItems
@@ -1135,7 +1133,15 @@ paths:
security: *ref_0
/api/public/dataset-run-items:
post:
- description: Create a dataset run item
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, create experiment data via the SDK
+ experiment runner or the OpenTelemetry endpoint at POST
+ /api/public/otel/v1/traces. See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Create a dataset run item
operationId: datasetRunItems_create
tags:
- DatasetRunItems
@@ -1181,7 +1187,16 @@ paths:
$ref: '#/components/schemas/CreateDatasetRunItemRequest'
deprecated: true
get:
- description: List dataset run items
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, dataset run items are replaced by
+ experiment items; use `GET
+ /api/public/experiment-items?fromStartTime=<from>&toStartTime=<to>`
+ instead. See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ List dataset run items
operationId: datasetRunItems_list
tags:
- DatasetRunItems
@@ -1390,7 +1405,15 @@ paths:
security: *ref_0
/api/public/datasets/{datasetName}/runs/{runName}:
get:
- description: Get a dataset run and its items
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, dataset runs are replaced by
+ experiments; use GET /api/public/experiments instead. See the [Langfuse
+ v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Get a dataset run and its items
operationId: datasets_getRun
tags:
- Datasets
@@ -1440,7 +1463,14 @@ paths:
security: *ref_0
deprecated: true
delete:
- description: Delete a dataset run and all its run items. This action is irreversible.
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, dataset runs are replaced by
+ experiments. See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Delete a dataset run and all its run items. This action is irreversible.
operationId: datasets_deleteRun
tags:
- Datasets
@@ -1491,7 +1521,15 @@ paths:
deprecated: true
/api/public/datasets/{datasetName}/runs:
get:
- description: Get dataset runs
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, dataset runs are replaced by
+ experiments; use GET /api/public/experiments instead. See the [Langfuse
+ v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Get dataset runs
operationId: datasets_getRuns
tags:
- Datasets
@@ -1896,6 +1934,14 @@ paths:
/api/public/ingestion:
post:
description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. Send data via the OpenTelemetry endpoint at `POST
+ /api/public/otel/v1/traces` instead, see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). See the
+ [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
**Legacy endpoint for batch ingestion for Langfuse Observability.**
@@ -1994,6 +2040,12 @@ paths:
/api/public/metrics:
get:
description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. Use `GET /api/public/v2/metrics?query=<urlencoded
+ json query>` instead. See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
Get metrics from the Langfuse project using a query object.
@@ -2095,7 +2147,15 @@ paths:
deprecated: true
/api/public/observations/{observationId}:
get:
- description: Get a observation
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. Use `GET
+ /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`
+ instead. See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Get a observation
operationId: legacy_observationsV1_get
tags:
- LegacyObservationsV1
@@ -2145,6 +2205,13 @@ paths:
/api/public/observations:
get:
description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. Use `GET
+ /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`
+ instead. See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
Get a list of observations.
@@ -4454,8 +4521,7 @@ paths:
security: *ref_0
post:
description: >-
- Create a new API key for a project (requires organization-scoped API
- key)
+ Create a new API key for a project (requires organization-scoped API key)
operationId: projects_createApiKey
tags:
- Projects
@@ -5169,7 +5235,13 @@ paths:
password:
type: string
nullable: true
- description: Initial password for the user
+ description: >-
+ Ignored. Accepted only for compatibility with identity
+ providers that always send a password on user creation (Okta
+ sends a placeholder value even when password sync is
+ disabled). No credential is created for the user;
+ provisioned users authenticate via SSO or set a password
+ themselves through the password reset flow.
required:
- userName
- name
@@ -5759,9 +5831,13 @@ paths:
$ref: '#/components/schemas/CreateScoreRequest'
/api/public/v2/scores:
get:
- description: |-
- **Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
- is no longer available on Langfuse v4 and later.
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint is not
+ available on Langfuse v4 and later and will be removed in a future
+ release. Use `GET /api/public/v3/scores` instead. See the [Langfuse v3
+ to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
Get a list of scores (supports both trace and session scores)
operationId: scores_get-many
@@ -5985,9 +6061,13 @@ paths:
deprecated: true
/api/public/v2/scores/{scoreId}:
get:
- description: |-
- **Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
- instead. This endpoint is no longer available on Langfuse v4 and later.
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint is not
+ available on Langfuse v4 and later and will be removed in a future
+ release. Use `GET /api/public/v3/scores` with the `id` filter instead.
+ See the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
Get a score (supports both trace and session scores)
operationId: scores_get-by-id
@@ -6037,6 +6117,14 @@ paths:
/api/public/sessions:
get:
description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, read session data via `GET
+ /api/public/v2/observations?filter=<urlencoded sessionId
+ filter>&fromStartTime=<from>&toStartTime=<to>`. See the [Langfuse v3 to
+ v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
Get sessions.
@@ -6137,6 +6225,14 @@ paths:
/api/public/sessions/{sessionId}:
get:
description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, read session data via `GET
+ /api/public/v2/observations?filter=<urlencoded sessionId
+ filter>&fromStartTime=<from>&toStartTime=<to>`. See the [Langfuse v3 to
+ v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
Get a session.
@@ -6195,7 +6291,15 @@ paths:
deprecated: true
/api/public/traces/{traceId}:
get:
- description: Get a specific trace
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, read span and trace data via `GET
+ /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`. See
+ the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Get a specific trace
operationId: trace_get
tags:
- Trace
@@ -6300,7 +6404,15 @@ paths:
security: *ref_0
/api/public/traces:
get:
- description: Get list of traces
+ description: >-
+ **Deprecated:** Langfuse v3 is deprecated; this endpoint will be removed
+ in a future release. In Langfuse v4, read span and trace data via `GET
+ /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`. See
+ the [Langfuse v3 to v4 upgrade
+ guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
+
+
+ Get list of traces
operationId: trace_list
tags:
- Trace
@@ -7794,8 +7906,7 @@ paths:
- name: evaluationRuleId
in: path
description: >-
- Evaluation rule identifier returned by the evaluation rule
- endpoints.
+ Evaluation rule identifier returned by the evaluation rule endpoints.
required: true
schema:
type: string
@@ -9830,8 +9941,7 @@ components:
type: number
format: double
description: >-
- The numeric value of the score. Equals 1 for "True" and 0 for
- "False"
+ The numeric value of the score. Equals 1 for "True" and 0 for "False"
stringValue:
type: string
description: >-
@@ -10017,8 +10127,7 @@ components:
type: number
format: double
description: >-
- The numeric value of the score. Equals 1 for "True" and 0 for
- "False"
+ The numeric value of the score. Equals 1 for "True" and 0 for "False"
stringValue:
type: string
description: >-
@@ -14406,8 +14515,7 @@ components:
model:
type: string
description: >-
- Model identifier exposed by the provider, for example
- `gpt-4.1-mini`.
+ Model identifier exposed by the provider, for example `gpt-4.1-mini`.
required:
- provider
- model
@@ -16483,8 +16591,7 @@ components:
id:
type: string
description: >-
- Identifier of the exact evaluator version currently used by the
- rule.
+ Identifier of the exact evaluator version currently used by the rule.
name:
type: string
description: Evaluator family name.
diff --git a/web/scripts/openapi/fern-deprecations.ts b/web/scripts/openapi/fern-deprecations.ts
index f17d916818..fb6cb59a2d 100644
--- a/web/scripts/openapi/fern-deprecations.ts
+++ b/web/scripts/openapi/fern-deprecations.ts
@@ -6,6 +6,7 @@ type FernAvailability =
| string
| {
status?: string;
+ message?: string;
};
type FernDefinition = {
@@ -27,6 +28,12 @@ type FernDefinition = {
export type DeprecatedOperation = {
method: string;
endpointPath: string;
+ /**
+ * Customer-facing explanation of what to use instead. Rendered as Markdown,
+ * so example calls need backticks or a `<placeholder>` is read as an HTML tag
+ * and disappears from the API reference.
+ */
+ message: string;
};
function listYamlFiles(directory: string): string[] {
@@ -54,6 +61,13 @@ function isDeprecated(availability: FernAvailability | undefined): boolean {
);
}
+function readMessage(availability: FernAvailability | undefined): string {
+ const message =
+ typeof availability === "object" ? (availability.message ?? "") : "";
+ // The message is folded into one line of the OpenAPI description.
+ return message.replace(/\s+/g, " ").trim();
+}
+
export function getFernDeprecatedOperations(
definitionDirectory: string,
): DeprecatedOperation[] {
@@ -69,7 +83,7 @@ export function getFernDeprecatedOperations(
if (!service?.endpoints) return [];
- return Object.values(service.endpoints).flatMap((endpoint) => {
+ return Object.entries(service.endpoints).flatMap(([name, endpoint]) => {
if (!isDeprecated(endpoint.availability)) return [];
if (!endpoint.method || endpoint.path === undefined) {
throw new Error(
@@ -77,6 +91,13 @@ export function getFernDeprecatedOperations(
);
}
+ const message = readMessage(endpoint.availability);
+ if (!message) {
+ throw new Error(
+ `Deprecated endpoint "${name}" in ${definitionPath} must define availability.message, which is what API consumers read in the reference`,
+ );
+ }
+
return [
{
method: endpoint.method.toLowerCase(),
@@ -86,6 +107,7 @@ export function getFernDeprecatedOperations(
endpoint["base-path"],
endpoint.path,
),
+ message,
},
];
});
diff --git a/web/scripts/openapi/stamp-deprecations.ts b/web/scripts/openapi/stamp-deprecations.ts
new file mode 100644
index 0000000000..fc8b8fb138
--- /dev/null
+++ b/web/scripts/openapi/stamp-deprecations.ts
@@ -0,0 +1,120 @@
+import assert from "node:assert/strict";
+import { isMap, isScalar, parse, parseDocument, Scalar } from "yaml";
+
+import { type DeprecatedOperation } from "./fern-deprecations";
+
+/** Fold width used by `fern export`. */
+const LINE_WIDTH = 80;
+
+/**
+ * Resolving the spec to plain JS repeats one `security` alias per operation,
+ * which trips the default alias-expansion guard. This file is our own build
+ * output, so the guard has nothing to protect here. `parseDocument` keeps
+ * aliases as nodes and needs no such option.
+ */
+const RESOLVE_OPTIONS = { maxAliasCount: -1 };
+
+const NOTICE_LABEL = "**Deprecated:**";
+/** Matches a notice this script wrote, so re-runs replace instead of stacking. */
+const NOTICE_PATTERN = /^\*\*Deprecated:\*\*[^\n]*(?:\n\n|$)/;
+
+/**
+ * Every deprecation in the definitions retires a Langfuse v3 endpoint, so the
+ * notice can point at the upgrade guide without each message repeating the link.
+ */
+const UPGRADE_GUIDE_URL =
+ "https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4";
+
+/** The notice put in front of a deprecated operation's description. */
+export function deprecationNotice(message: string): string {
+ return `${NOTICE_LABEL} ${message} See the [Langfuse v3 to v4 upgrade guide](${UPGRADE_GUIDE_URL}).`;
+}
+
+type OpenApiOperation = { deprecated?: boolean; description?: string };
+type OpenApiDocument = {
+ paths: Record<string, Record<string, OpenApiOperation>>;
+};
+
+/**
+ * Writes prose the way the export writes its own: a block scalar once it spans
+ * lines, folded unless the field was already literal.
+ */
+function descriptionScalar(
+ description: string,
+ previous?: Scalar.Type,
+): Scalar<string> | string {
+ if (!description.includes("\n")) return description;
+
+ const scalar = new Scalar(description);
+ scalar.type =
+ previous === Scalar.BLOCK_LITERAL
+ ? Scalar.BLOCK_LITERAL
+ : Scalar.BLOCK_FOLDED;
+ return scalar;
+}
+
+/**
+ * Writes the standard OpenAPI `deprecated` flag and a `**Deprecated:** …`
+ * notice onto every operation Fern marks deprecated.
+ *
+ * Printing the parsed document reflows a handful of long descriptions the
+ * exporter had folded differently, which is why the result is checked against
+ * the expected document: formatting may move, meaning may not.
+ */
+export function stampDeprecations(
+ source: string,
+ operations: DeprecatedOperation[],
+): string {
+ const document = parseDocument(source);
+ if (document.errors.length > 0) {
+ throw new Error(document.errors.map((error) => error.message).join("\n"));
+ }
+
+ const expected = parse(source, RESOLVE_OPTIONS) as OpenApiDocument;
+
+ for (const { method, endpointPath, message } of operations) {
+ const label = `${method.toUpperCase()} ${endpointPath}`;
+ const operation = document.getIn(["paths", endpointPath, method], true);
+
+ if (!isMap(operation)) {
+ throw new Error(`OpenAPI schema does not contain ${label}`);
+ }
+
+ const deprecated = operation.get("deprecated");
+ if (deprecated !== undefined && deprecated !== true) {
+ throw new Error(`${label} has an invalid deprecated value`);
+ }
+
+ const previous = operation.get("description", true);
+ const base = isScalar(previous)
+ ? String(previous.value ?? "").replace(NOTICE_PATTERN, "")
+ : "";
+ if (base.startsWith("**Deprecated")) {
+ throw new Error(
+ `${label} opens its Fern docs with a hand-written deprecation notice, which would render twice; keep that text in availability.message instead`,
+ );
+ }
+
+ const notice = deprecationNotice(message);
+ const description = base ? `${notice}\n\n${base}` : notice;
+
+ operation.set("deprecated", true);
+ operation.set(
+ "description",
+ descriptionScalar(
+ description,
+ isScalar(previous) ? previous.type : undefined,
+ ),
+ );
+
+ const target = expected.paths[endpointPath][method];
+ target.deprecated = true;
+ target.description = description;
+ }
+
+ const text = document.toString({ lineWidth: LINE_WIDTH });
+ // Nothing may change beyond the two fields on the operations we touched.
+ assert.deepStrictEqual(parse(text, RESOLVE_OPTIONS), expected);
+
+ return text;
+}
diff --git a/web/scripts/openapi/sync-deprecations.ts b/web/scripts/openapi/sync-deprecations.ts
index 7de1416e4d..ecf8b932be 100644
--- a/web/scripts/openapi/sync-deprecations.ts
+++ b/web/scripts/openapi/sync-deprecations.ts
@@ -1,8 +1,8 @@
import fs from "node:fs";
import path from "node:path";
-import { isMap, parseDocument } from "yaml";
import { getFernDeprecatedOperations } from "./fern-deprecations";
+import { stampDeprecations } from "./stamp-deprecations";
const webDirectory = process.cwd();
const definitionDirectory = path.resolve(
@@ -14,60 +14,12 @@ const openApiPath = path.resolve(
"public/generated/api/openapi.yml",
);
-let openApiSource = fs.readFileSync(openApiPath, "utf8");
-const openApi = parseDocument(openApiSource);
-
-if (openApi.errors.length > 0) {
- throw new Error(openApi.errors.map((error) => error.message).join("\n"));
-}
-
const deprecatedOperations = getFernDeprecatedOperations(definitionDirectory);
-const insertions: Array<{ offset: number; value: string }> = [];
-
-for (const { method, endpointPath } of deprecatedOperations) {
- const operation = openApi.getIn(["paths", endpointPath, method], true);
-
- if (!isMap(operation)) {
- throw new Error(
- `OpenAPI schema does not contain ${method.toUpperCase()} ${endpointPath}`,
- );
- }
-
- const deprecated = operation.get("deprecated");
- if (deprecated === true) continue;
- if (deprecated !== undefined) {
- throw new Error(
- `${method.toUpperCase()} ${endpointPath} has an invalid deprecated value`,
- );
- }
- if (!operation.range) {
- throw new Error(
- `Cannot locate ${method.toUpperCase()} ${endpointPath} in the OpenAPI source`,
- );
- }
-
- const operationLineStart =
- openApiSource.lastIndexOf("\n", operation.range[0]) + 1;
- const insertionOffset =
- openApiSource.lastIndexOf("\n", operation.range[1] - 1) + 1;
- const indentation = openApiSource.slice(
- operationLineStart,
- operation.range[0],
- );
-
- insertions.push({
- offset: insertionOffset,
- value: `${indentation}deprecated: true\n`,
- });
-}
+const openApiSource = fs.readFileSync(openApiPath, "utf8");
+const syncedSource = stampDeprecations(openApiSource, deprecatedOperations);
-for (const { offset, value } of insertions.sort(
- (left, right) => right.offset - left.offset,
-)) {
- openApiSource = `${openApiSource.slice(0, offset)}${value}${openApiSource.slice(offset)}`;
-}
+if (syncedSource !== openApiSource) fs.writeFileSync(openApiPath, syncedSource);
-fs.writeFileSync(openApiPath, openApiSource);
console.log(
`Synced ${deprecatedOperations.length} deprecated OpenAPI operations from Fern definitions.`,
);
diff --git a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts
index a4fb3d3f2b..d7f2119315 100644
--- a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts
+++ b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts
@@ -3,10 +3,22 @@ import os from "node:os";
import path from "node:path";
import { parse } from "yaml";
-import { getFernDeprecatedOperations } from "../../../../scripts/openapi/fern-deprecations";
+import {
+ getFernDeprecatedOperations,
+ type DeprecatedOperation,
+} from "../../../../scripts/openapi/fern-deprecations";
+import {
+ deprecationNotice,
+ stampDeprecations,
+} from "../../../../scripts/openapi/stamp-deprecations";
+type OpenApiOperation = {
+ deprecated?: boolean;
+ description?: string;
+ security?: unknown;
+};
type OpenApiDocument = {
- paths: Record<string, Record<string, { deprecated?: boolean }>>;
+ paths: Record<string, Record<string, OpenApiOperation>>;
};
const definitionDirectory = path.resolve(
@@ -18,11 +30,67 @@ const openApiPath = path.resolve(
"public/generated/api/openapi.yml",
);
+const MESSAGE = "Use `GET /api/public/v2/observations?from=<from>` instead.";
+
+/** Spec fixture in the shape `fern export` produces, aliased `security` included. */
+const SPEC = `openapi: 3.0.1
+paths:
+ /api/public/traces:
+ get:
+ description: Get list of traces
+ operationId: trace_list
+ security: &ref_0
+ - BasicAuth: []
+ post:
+ description: Create a trace
+ operationId: trace_create
+ security: *ref_0
+ /api/public/sessions:
+ get:
+ description: >-
+ Get sessions.
+
+
+ Sessions group traces that belong to one conversation.
+ operationId: sessions_list
+ security: *ref_0
+`;
+
+function operations(
+ entries: Array<[string, string, string]>,
+): DeprecatedOperation[] {
+ return entries.map(([method, endpointPath, message]) => ({
+ method,
+ endpointPath,
+ message,
+ }));
+}
+
+function parseSpec(source: string): OpenApiDocument {
+ return parse(source, { maxAliasCount: -1 }) as OpenApiDocument;
+}
+
+function withDefinition(
+ files: Record<string, string>,
+ assertions: (directory: string) => void,
+) {
+ const directory = fs.mkdtempSync(
+ path.join(os.tmpdir(), "fern-deprecations-"),
+ );
+
+ try {
+ for (const [name, contents] of Object.entries(files)) {
+ fs.writeFileSync(path.join(directory, name), contents);
+ }
+ assertions(directory);
+ } finally {
+ fs.rmSync(directory, { recursive: true });
+ }
+}
+
describe("OpenAPI deprecations", () => {
it("matches the deprecated endpoints in the Fern definitions", () => {
- const openApi = parse(fs.readFileSync(openApiPath, "utf8"), {
- maxAliasCount: -1,
- }) as OpenApiDocument;
+ const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));
const openApiDeprecatedOperations = Object.entries(openApi.paths).flatMap(
([endpointPath, pathItem]) =>
Object.entries(pathItem).flatMap(([method, operation]) =>
@@ -37,35 +105,172 @@ describe("OpenAPI deprecations", () => {
);
});
+ it("carries every Fern deprecation message into the operation description", () => {
+ const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));
+
+ for (const { method, endpointPath, message } of getFernDeprecatedOperations(
+ definitionDirectory,
+ )) {
+ expect(
+ openApi.paths[endpointPath][method].description,
+ `${method.toUpperCase()} ${endpointPath}`,
+ ).toContain(deprecationNotice(message));
+ }
+ });
+
it("supports deprecated endpoints at a service base path", () => {
- const fixtureDirectory = fs.mkdtempSync(
- path.join(os.tmpdir(), "fern-deprecations-"),
+ withDefinition(
+ {
+ "api.yml": "base-path: /api\n",
+ "service.yml": [
+ "service:",
+ " base-path: /public",
+ " endpoints:",
+ " get:",
+ " availability:",
+ " status: deprecated",
+ ` message: "${MESSAGE}"`,
+ " method: GET",
+ ' path: ""',
+ "",
+ ].join("\n"),
+ },
+ (directory) => {
+ expect(getFernDeprecatedOperations(directory)).toEqual([
+ { method: "get", endpointPath: "/api/public", message: MESSAGE },
+ ]);
+ },
);
+ });
- try {
- fs.writeFileSync(
- path.join(fixtureDirectory, "api.yml"),
- "base-path: /api\n",
- );
- fs.writeFileSync(
- path.join(fixtureDirectory, "service.yml"),
- [
+ it("refuses a deprecation without a message", () => {
+ withDefinition(
+ {
+ "api.yml": "base-path: /api\n",
+ "service.yml": [
"service:",
- " base-path: /public",
" endpoints:",
" get:",
" availability: deprecated",
" method: GET",
- ' path: ""',
+ " path: /traces",
"",
].join("\n"),
- );
+ },
+ (directory) => {
+ expect(() => getFernDeprecatedOperations(directory)).toThrow(
+ /must define availability.message/,
+ );
+ },
+ );
+ });
- expect(getFernDeprecatedOperations(fixtureDirectory)).toEqual([
- { method: "get", endpointPath: "/api/public" },
- ]);
- } finally {
- fs.rmSync(fixtureDirectory, { recursive: true });
- }
+ it("stamps the flag and the notice, leaving other operations untouched", () => {
+ const stamped = stampDeprecations(
+ SPEC,
+ operations([["get", "/api/public/traces", MESSAGE]]),
+ );
+ const openApi = parseSpec(stamped);
+ const operation = openApi.paths["/api/public/traces"].get;
+
+ expect(operation.deprecated).toBe(true);
+ expect(operation.description).toBe(
+ `${deprecationNotice(MESSAGE)}\n\nGet list of traces`,
+ );
+
+ const untouched = openApi.paths["/api/public/traces"].post;
+ expect(untouched.description).toBe("Create a trace");
+ expect(untouched.deprecated).toBeUndefined();
+ expect(stamped).toContain(" description: Create a trace\n");
+ });
+
+ it("keeps the aliased security block intact", () => {
+ const stamped = stampDeprecations(
+ SPEC,
+ operations([["get", "/api/public/traces", MESSAGE]]),
+ );
+
+ expect(stamped.match(/security: \*ref_0/g)).toHaveLength(2);
+ expect(
+ parseSpec(stamped).paths["/api/public/traces"].post.security,
+ ).toEqual([{ BasicAuth: [] }]);
+ });
+
+ it("preserves the block style and text of a multi-line description", () => {
+ const stamped = stampDeprecations(
+ SPEC,
+ operations([["get", "/api/public/sessions", MESSAGE]]),
+ );
+
+ expect(stamped).toContain(" description: >-\n");
+ expect(stamped).toContain(
+ " Sessions group traces that belong to one conversation.\n",
+ );
+ expect(
+ parseSpec(stamped).paths["/api/public/sessions"].get.description,
+ ).toBe(
+ `${deprecationNotice(MESSAGE)}\n\nGet sessions.\n\nSessions group traces that belong to one conversation.`,
+ );
+ });
+
+ it("keeps a literal description literal instead of folding it", () => {
+ const literal = SPEC.replace("description: >-", "description: |-");
+ const stamped = stampDeprecations(
+ literal,
+ operations([["get", "/api/public/sessions", MESSAGE]]),
+ );
+
+ expect(stamped).toContain(" description: |-\n");
+ expect(
+ parseSpec(stamped).paths["/api/public/sessions"].get.description,
+ ).toContain(deprecationNotice(MESSAGE));
+ });
+
+ it("is idempotent across repeated runs", () => {
+ const deprecated = operations([
+ ["get", "/api/public/traces", MESSAGE],
+ ["get", "/api/public/sessions", MESSAGE],
+ ]);
+ const once = stampDeprecations(SPEC, deprecated);
+
+ expect(stampDeprecations(once, deprecated)).toBe(once);
+ });
+
+ it("replaces an outdated notice instead of stacking a second one", () => {
+ const once = stampDeprecations(
+ SPEC,
+ operations([["get", "/api/public/traces", "Old guidance."]]),
+ );
+ const twice = stampDeprecations(
+ once,
+ operations([["get", "/api/public/traces", "New guidance."]]),
+ );
+
+ expect(parseSpec(twice).paths["/api/public/traces"].get.description).toBe(
+ `${deprecationNotice("New guidance.")}\n\nGet list of traces`,
+ );
+ });
+
+ it("refuses a description that already opens with a hand-written notice", () => {
+ const handWritten = SPEC.replace(
+ "description: Get list of traces",
+ "description: '**Deprecated.** Use something else.'",
+ );
+
+ expect(() =>
+ stampDeprecations(
+ handWritten,
+ operations([["get", "/api/public/traces", MESSAGE]]),
+ ),
+ ).toThrow(/hand-written deprecation notice/);
+ });
+
+ it("fails when a deprecated endpoint has no operation in the spec", () => {
+ expect(() =>
+ stampDeprecations(
+ SPEC,
+ operations([["get", "/api/public/does-not-exist", MESSAGE]]),
+ ),
+ ).toThrow(/does not contain GET \/api\/public\/does-not-exist/);
});
});