К основному содержанию
скилл CX Codex

api-platform-versioning — скилл для Claude Code: версии API Platform

Скилл api-platform-versioning помогает менять API на API Platform без ломающих релизов: сначала депрекация с датой sunset, параллельные версии — в крайнем случае.

MIT ★ 234 обновлён 2026-10-05

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/api-platform-versioning/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/api-platform-versioning/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
api-versioning codewithmukesh Скилл api-versioning направляет агента при версионировании ASP.NET Core API через библиотеку Asp.Versioning. Помогает настроить пути, заголовки и мягкую депрекацию устаревших версий. CX Codex +1 4 000установок api-versioning-strategy secondsky Скилл api-versioning-strategy помогает выбрать способ версионирования API и провести старую версию до отключения без сюрпризов для клиентов. CX Codex +1 417установок api-versioning-policy Samuel Berthe Скилл api-versioning-policy помогает составить регламент версионирования и вывода API из эксплуатации. Пригодится при подготовке к ломающим изменениям или переходу на схему /v2. CX Codex +1 10 100установок api-versioning-deprecation-planner patricio0312rev Скилл api-versioning-deprecation-planner помогает выбрать стратегию версионирования API, составить план отказа от старой версии и подготовить руководство для перехода клиентов. CX Codex +1 264установок symfony-specialist VoltAgent Community Субагент symfony-specialist для Claude, который ведёт разработку на Symfony 6.4, 7.x и 8.0: сущности Doctrine, асинхронная обработка через Messenger, ресурсы API Platform. CX Codex ★ 26 718звёзд репо api-design-expert personamanagmentlayer Скилл api-design-expert для проектирования HTTP API: ресурсы REST, выбор между GraphQL и gRPC, схемы версионирования и единый формат ошибок. Полезен до того, как написан первый эндпоинт. CX Codex +1 180установок

Из того же набора51

Весь набор →
api-platform-tests Скилл api-platform-tests помогает писать функциональные тесты ресурсов API Platform на Symfony: проверять ответы, фильтры, схемы JSON и доступ. Пригодится при добавлении или изменении API-эндпоинтов. CX Codex +1 ★ 234звёзд репо api-platform-serialization Скилл api-platform-serialization настраивает сериализацию API Platform: группы полей на операцию, IRI вместо вложенных объектов, вычисляемые свойства и опции нормализаторов. CX Codex +1 ★ 234звёзд репо symfony-scheduler Настраивает периодические задачи через Symfony Scheduler без системного cron. Запускает генерацию отчётов, очистку данных и синхронизации через Symfony Messenger. CX Codex +1 ★ 234звёзд репо tdd-with-pest Скилл tdd-with-pest для Claude Code ведёт разработку в Symfony через RED-GREEN-REFACTOR с Pest v4. Создаёт тесты, воспроизводит баги и переносит PHPUnit-тесты на синтаксис Pest. CX Codex +1 ★ 234звёзд репо functional-tests Скилл functional-tests помогает писать функциональные тесты контроллеров и сервисов Symfony на базе WebTestCase, KernelTestCase и DAMA rollback. CX Codex +1 ★ 234звёзд репо doctrine-migrations Скилл doctrine-migrations помогает создавать и проверять миграции Doctrine, откатывать версии и готовить их к запуску в production. Пригодится при изменениях схемы Symfony-приложения. CX Codex +1 ★ 234звёзд репо symfony-messenger Скилл для работы с асинхронными сообщениями через Symfony Messenger: настройка транспортов, обработчиков и стратегий повтора. CX Codex +1 ★ 234звёзд репо api-platform-security Скилл api-platform-security настраивает правила доступа в Symfony API Platform через выражения security, воутеры и хуки жизненного цикла операций. CX Codex +1 ★ 234звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой