skills.rest
lightdash
lightdashOFFICIAL
Explore all skills by this author →
Website𝕏@lightdash_devsGitHub

deprecate-endpoint

Wire deprecation middleware, headers, and docs banners onto TSOA controller routes.

6.1k|768|Updated Mar 19, 2021
Search Tags:#OpenAPI#Backend#Mintlify#sunset#rest endpoint#tsoa#API deprecation
One-click install
npx skills add https://github.com/lightdash/lightdash --skill deprecate-endpoint
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: deprecate-endpoint
Source: https://github.com/lightdash/lightdash/tree/main/.claude/skills/deprecate-endpoint
Command: npx skills add https://github.com/lightdash/lightdash --skill deprecate-endpoint

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Deprecating a backend HTTP endpoint in Lightdash involves many easy-to-miss steps: JSDoc tags, TSOA decorators, shared middleware wiring, OpenAPI regeneration, and docs-site visibility. This Skill provides a checklist so nothing is forgotten and deprecated routes behave consistently.

Core Features & Use Cases

  • Deprecation wiring checklist: Add @deprecated JSDoc, @Deprecated() decorator, and getDeprecatedRouteMiddleware with a deprecation date and replacement hint to a TSOA controller route.
  • First-party caller precondition: Grep frontend, CLI, EE code, and test suites to confirm no internal caller still hits the route before deprecating it.
  • Docs visibility: Shape the JSDoc description first line and add an x-mint Mintlify banner so the deprecation appears on docs.lightdash.com and llms.txt, then regenerate swagger.json.
  • Use Case: When replacing a v1 endpoint with a v2 equivalent, use this Skill to mark the old route deprecated, set its sunset date, and surface the migration path in the API reference.

Quick Start

Deprecate the GET role assignments endpoint in the project controller and point callers to the v2 replacement.

Frequently Asked Questions about deprecate-endpoint

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I deprecate a REST API endpoint in a TSOA controller?▼

Add a @deprecated JSDoc line naming the replacement, the @Deprecated() decorator, and getDeprecatedRouteMiddleware with a deprecation date to the handler's @Middlewares array. Then regenerate the OpenAPI spec with pnpm generate-api.

How do I make a deprecated endpoint visible in Mintlify API docs?▼

Make the JSDoc description's first line plain text starting with 'Deprecated — use ...' and add an @Extension('x-mint', ...) banner with a Warning block. The docs site and llms.txt are generated from swagger.json on the main branch.

When can I safely deprecate an API endpoint?▼

Only after no first-party caller remains. Grep the frontend, CLI, common, EE backend, api-tests, and e2e packages for the route path, and migrate any remaining callers first, since deprecated routes log errors and alert Sentry past their sunset date.

What is the default sunset period for a deprecated endpoint?▼

The removal date defaults to three months after the deprecation date passed to getDeprecatedRouteMiddleware. You can override it by passing a removeOn option when a different sunset has been agreed.

Should I deprecate internal service methods or database columns the same way?▼

No. The deprecation middleware applies only to HTTP route handlers. Internal service methods, type fields, DB columns, and config fields should just get a plain @deprecated JSDoc comment.

Related Skills

Explore More Software Engineering Skills→
gptdeividgptdeivid

copilotkit-upgrade

Migrate CopilotKit v1 applications to v2 with AG-UI runtime updates.

Community
Advanced
yu-iskwyu-iskw

sync-openapi-types

Regenerate Lightdash API TypeScript types from swagger.json and verify the monorepo.

Community
Intermediate
achmfachmf

sentry-feature-setup

Configure Sentry AI/LLM tracing, OpenTelemetry pipelines, and alerting workflows.

Community
Intermediate
pelletencatepelletencate

api-versioning

Implement versioned Rails 8 API namespaces and controllers with deprecation workflows.

Community
Advanced