api-platform-versioning — скилл для Claude Code: версии API Platform
Скилл api-platform-versioning помогает менять API на API Platform без ломающих релизов: сначала депрекация с датой sunset, параллельные версии — в крайнем случае.
MIT ★ 234 обновлён 2026-10-05
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-codeЧто делает api-platform-versioning
Скилл задаёт порядок, в котором API Platform переживает ломающее изменение. Начинают с депрекации: deprecationReason ставится на ресурс, на операцию или на #[ApiProperty]. Дальше идёт sunset: с датой, а на v4 ещё и headers с Deprecation (RFC 9745) и Link с rel="successor-version". До v4 те же заголовки отдают из слушателя KernelEvents::RESPONSE.
Параллельные /v1 и /v2 — запасной путь. Их делают через разные uriTemplate и отдельные группы либо через output DTO со своим провайдером на версию. В конце старую операцию помечают устаревшей в OpenAPI, описывают изменения по версиям и прогоняют тесты на каждой живой версии.
Одна деталь: опция headers относится к v4, на v3 её нет — проверьте, что стоит у вас. Ещё скилл держит потолок в 2–3 активные версии и советует закрывать мелкие добавления группами. Внутри лежит reference.md с деталями реализации; инструменты: чтение, поиск, правка файлов и Bash.
Какие задачи решает
- пометить поле устаревшим, не ломая клиентов
- назначить дату отключения и отдать её в заголовке
Sunset - свести
/v1и/v2одного эндпоинта в одном приложении - описать изменения по версиям в OpenAPI
- проверить, что тесты проходят на каждой живой версии
Примеры запросов агенту
- Помечу
legacyPriceкак устаревшее поле с датой отключения — покажи, как это сделать черезdeprecationReasonиsunset. - Нужно выпустить
/v2рядом с/v1: распиши вариант с разнымиuriTemplateи группами. - Проверь, что на нашей версии API Platform реально отдаются заголовки
DeprecationиLink.
Как установить api-platform-versioning
1Через Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code2Вручную: положить файлы
~/.claude/skills/api-platform-versioning/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/api-platform-versioning/
1Через Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a codex2Вручную: положить файлы
.agents/skills/api-platform-versioning/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a cursor2Вручную: положить файлы
.cursor/skills/api-platform-versioning/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install dev-toolings/superpowers-symfony content/skills/api-platform-versioning2Вручную: положить файлы
.github/skills/api-platform-versioning/SKILL.md1Через Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a gemini-cli2Командой платформы
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/api-platform-versioningВручную: положить файлы
.devin/skills/api-platform-versioning/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об api-platform-versioning
Как установить api-platform-versioning в Claude Code?
Выполните npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code. Скилл окажется в ~/.claude/skills/api-platform-versioning/SKILL.md.
Что делает api-platform-versioning?
Проводит Claude по эволюции API на API Platform: депрекация с датой sunset и ссылкой на преемника, а параллельные версии — только если ломающее изменение иначе не выразить.
Когда вместо депрекации нужны /v1 и /v2?
Когда депрекация и группы не описывают изменение представления. Скилл считает версионирование путей запасным вариантом и советует держать не больше 2–3 активных версий.
Исходный текст
SKILL.md · MIT
--- name: api-platform-versioning description: Evolve API Platform APIs via deprecation (deprecationReason/sunset, RFC 8594/9745), the recommended alternative to versioning; plus path/header strategies capabilities: [read, search, edit, shell] tags: [api-platform] # projected by `bun run build` — do not edit by hand allowed-tools: - Read - Glob - Grep - Write - Edit - Bash --- # Api Platform Versioning (Symfony) ## Use when - A field, operation, or resource is being renamed or removed and consumers need time to migrate. - Announcing a removal date to clients with `Sunset` and `Deprecation` headers. - Deciding between deprecation and parallel `/v1` and `/v2` surfaces. - A breaking representation change that deprecation and groups cannot express. ## Default workflow 1. Try deprecation first: set `deprecationReason` on the resource, the operation, or `#[ApiProperty]`. 2. Add `sunset:` with a date, and on v4 add `headers` carrying `Deprecation` (RFC 9745) and a `Link` with `rel="successor-version"`. 3. Before v4, emit those headers from a `KernelEvents::RESPONSE` listener. 4. Only if still breaking, expose parallel `uriTemplate` values (`/v1`, `/v2`) with distinct groups, or output DTOs with one provider per version. 5. Mark the old operation as deprecated in OpenAPI, document the changes per version, and test every active version. ## Guardrails - Prefer deprecation: path versioning is the fallback, not the default. - Always set a sunset date and keep at most 2 or 3 versions active. - `deprecationReason` and `sunset` are stable across v3 and v4, but the RFC 9745 `headers` option is v4-era: verify it on your installed version. - Use groups for minor additive changes rather than a new version. ## Progressive disclosure - Use this file for execution posture and risk controls. - Open references when deep implementation details are needed. ## Output contract - The deprecation or versioning strategy chosen and why. - Deprecated elements with their sunset dates and successor links. - Tests for each active version and for the headers. ## References - `reference.md`
© dev-toolings · MIT · dev-toolings/superpowers-symfony