Help us improve
Share bugs, ideas, or general feedback.
From dex-skill-api-documentation
OpenAPI/Swagger — ловушки spec, генерации клиентов. Активируется при swagger, openapi, swashbuckle, nswag, Kiota, ProducesResponseType, XML comments, JsonStringEnumConverter, schema drift, api doc
How this skill is triggered — by the user, by Claude, or both
Slash command
/dex-skill-api-documentation:api-documentationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Ловушки контроллеров (ActionResult, CancellationToken, толстые контроллеры) — см. `dex-skill-api-development`
Share bugs, ideas, or general feedback.
Ловушки контроллеров (ActionResult, CancellationToken, толстые контроллеры) — см.
dex-skill-api-developmentЗдесь: только OpenAPI/Swagger/NSwag/Kiota ловушки
Плохо: OpenAPI spec пишется вручную отдельно от кода Правильно: генерация spec из кода (Swashbuckle/NSwag) или code-first + CI проверка Почему: ручная spec устаревает после первого же рефакторинга. Клиенты генерируют код по старой spec → runtime ошибки
[ProducesResponseType] → Swagger показывает только 200Плохо: endpoint возвращает 404, 422, 409, но Swagger показывает только 200 OK
Правильно: [ProducesResponseType(typeof(ProblemDetails), 404)] на каждый возможный статус
Почему: сгенерированные клиенты не обрабатывают 404/422 → необработанные ошибки в runtime
Плохо: написал <summary>, <example> на моделях, но Swagger их не показывает
Правильно: <GenerateDocumentationFile>true</GenerateDocumentationFile> в .csproj
Почему: без этого флага XML comments компилятором не генерируются. Swashbuckle молча их игнорирует — ни ошибки, ни предупреждения
<example> отсутствует на request моделяхПлохо: public record CreateProductRequest(string Name, decimal Price) — Swagger показывает "string", 0
Правильно: XML <example> на каждом свойстве → Swagger показывает реалистичные значения
Почему: разработчик клиента копирует пример из Swagger. "string" → отправляет "string" как имя → баг
Плохо: nswag openapi2csclient запускается вручную разработчиком
Правильно: генерация клиента в CI + diff-check (spec изменилась → клиент пересоздаётся)
Почему: spec обновили, клиент забыли перегенерировать → вызовы несуществующих endpoints, неправильные типы
Плохо: "status": 2 — клиент получает число, не знает что значит
Правильно: JsonStringEnumConverter + SchemaFilter → "status": "Approved"
Почему: числовой enum ломает клиентов при изменении порядка. Добавление значения в середину enum сдвигает все числа
Плохо: string? MiddleName генерируется как required в OpenAPI
Правильно: SupportNonNullableReferenceTypes() в Swashbuckle 6+ или [Required] explicit
Почему: клиент считает поле обязательным, отправляет пустую строку вместо null → некорректные данные
Плохо: v1 и v2 endpoints в одном Swagger UI → клиент не понимает что deprecated
Правильно: отдельный SwaggerDoc на каждую версию + [ApiVersion] + [MapToApiVersion]
Почему: клиенты v1 видят v2 endpoints, пробуют вызвать → 404 или неожиданный формат ответа
Плохо: endpoint заменён новым, но старый без [Obsolete] → клиенты продолжают использовать
Правильно: [Obsolete] → Swagger показывает strikethrough + deprecated: true в spec
Почему: без пометки клиенты не мигрируют. Когда удалишь endpoint — массовый сбой
[ProducesResponseType] на каждый возможный HTTP statusGenerateDocumentationFile в .csproj<example> на request/response моделяхJsonStringEnumConverter)[Obsolete]npx claudepluginhub dex-it/claude-code-marketplace --plugin dex-skill-api-documentationFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.