🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
fix(api): carry endpoint deprecation notices into the API reference (#16121)
Niklas Semmlerb3283dccc595
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 referencpnpm 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.ymlindex 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: GETdocs: List dataset run itemspath: /dataset-run-itemsdiff --git a/fern/apis/server/definition/ingestion.yml b/fern/apis/server/definition/ingestion.ymlindex 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.ymlindex 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.ymlindex 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 observationmethod: GETpath: /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.ymlindex 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: GETpath: /v2/scoresrequest:@@ -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: GETpath: /v2/scores/{scoreId}path-parameters:diff --git a/fern/apis/server/definition/sessions.yml b/fern/apis/server/definition/sessions.ymlindex 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.ymlindex 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 tracemethod: GETpath: /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 tracesmethod: GETpath: /tracesdiff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex dd5f1517e4..b7fc04a762 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -804,8 +804,7 @@ paths:- name: objectTypein: querydescription: >-- Filter comments by object type (trace, observation, session,- prompt).+ Filter comments by object type (trace, observation, session, prompt).required: falseschema:type: string@@ -1089,8 +1088,7 @@ paths:security: *ref_0delete: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_deletetags:- 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 itemoperationId: datasetRunItems_createtags:- DatasetRunItems@@ -1181,7 +1187,16 @@ paths:$ref: '#/components/schemas/CreateDatasetRunItemRequest'deprecated: trueget:- 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 itemsoperationId: datasetRunItems_listtags:- 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 itemsoperationId: datasets_getRuntags:- Datasets@@ -1440,7 +1463,14 @@ paths:security: *ref_0deprecated: truedelete:- 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_deleteRuntags:- 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 runsoperationId: datasets_getRunstags:- 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 observationoperationId: legacy_observationsV1_gettags:- 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_0post: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_createApiKeytags:- Projects@@ -5169,7 +5235,13 @@ paths:password:type: stringnullable: 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 traceoperationId: trace_gettags:- 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 tracesoperationId: trace_listtags:- Trace@@ -7794,8 +7906,7 @@ paths:- name: evaluationRuleIdin: pathdescription: >-- Evaluation rule identifier returned by the evaluation rule- endpoints.+ Evaluation rule identifier returned by the evaluation rule endpoints.required: trueschema:type: string@@ -9830,8 +9941,7 @@ components:type: numberformat: doubledescription: >-- 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: stringdescription: >-@@ -10017,8 +10127,7 @@ components:type: numberformat: doubledescription: >-- 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: stringdescription: >-@@ -14406,8 +14515,7 @@ components:model:type: stringdescription: >-- 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: stringdescription: >-- Identifier of the exact evaluator version currently used by the- rule.+ Identifier of the exact evaluator version currently used by the rule.name:type: stringdescription: Evaluator family name.diff --git a/web/scripts/openapi/fern-deprecations.ts b/web/scripts/openapi/fern-deprecations.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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/);});});