Поля OpenAPI
Ключи описания задаются константами OpenApiConfig — см. полный справочник.
Поля OpenAPI в карте задают описание операции: название, параметры, тело запроса и ответы. Здесь показано, как дополнить или переопределить автоматически сформированное описание.
Поля операции
Поля задаются на одном уровне с controller, parameters и security.
Название и оформление
| Ключ | Назначение |
|---|---|
| tags | Разделы документации |
| summary | Краткое название операции |
| description | Подробное описание |
| operationId | Идентификатор операции |
| externalDocs | Внешняя документация: url, description |
| deprecated | Признак устаревшей операции |
| servers | Серверы конкретной операции |
use Native\Api\Config\Internals\OpenApiConfig;
// Название и раздел операции
OpenApiConfig::SUMMARY => 'Получить заказ',
OpenApiConfig::DESCRIPTION => 'Возвращает заказ по ID',
OpenApiConfig::OPERATION_ID => 'getOrder',
OpenApiConfig::TAGS => ['Заказы'],Запрос и ответ
| Ключ | Назначение |
|---|---|
| parameters | Параметры пути, строки запроса и заголовков |
| requestBody | Тело запроса |
| responses | Ответы по HTTP-статусам |
| security | Требования авторизации в документации |
| callbacks | Описания обратных вызовов |
| components.schemas | Именованные схемы для $ref |
Автозаполнение
Эти сведения уже формируются из карты — повторять их в полях OpenAPI не нужно.
| Что формируется | Источник |
|---|---|
| Название | summary → description → адрес роута |
| Раздел | tags, иначе первый сегмент адреса |
| Параметры пути | Фигурные скобки адреса; всегда обязательны |
| Остальные параметры | requestBody для POST, PUT и PATCH; query для остальных методов |
| Тип параметра | type из карты параметров. Если не задан, в документации указывается string |
| Авторизация | login → basicAuth, token → bearerAuth |
| Успешный ответ | POST → 201, DELETE → 204, остальные → 200 |
| Допустимые значения | Список possibleValue → enum; диапазон → minimum и maximum |
Совпадающие ключи
parameters
| Формат | Назначение |
|---|---|
| Карта по именам параметров | Проверки модуля и автоматическое описание |
| Числовой список OpenAPI | Только описание; проверки параметров не создаются |
use Native\Api\Config\Internals\OpenApiConfig;
// Только описание заголовка в документации
OpenApiConfig::PARAMETERS => [
[
OpenApiConfig::NAME => 'X-Client-Version',
OpenApiConfig::IN => 'header',
OpenApiConfig::REQUIRED => false,
OpenApiConfig::SCHEMA => [OpenApiConfig::TYPE => 'string'],
OpenApiConfig::EXAMPLE => '1.0',
],
],security
| Формат | Назначение |
|---|---|
Ключи auth, token_type, group, ip | Проверки доступа и автоматическое описание |
| Числовой список OpenAPI | Только описание авторизации; проверку не включает |
group и ip задают проверки доступа, но не создают схемы авторизации OpenAPI.
use Native\Api\Config\Internals\OpenApiConfig;
// Только описание Bearer-авторизации в документации
OpenApiConfig::SECURITY => [
[SecurityConfig::SECURITY_SCHEME_BEARER => []],
],Переопределение
Тело запроса
Явный requestBody заменяет автоматический. Для GET и HEAD тело исключается.
Для вложенного объекта задайте описание явно: генератор описывает type => array как массив объектов.
use Native\Api\Config\Internals\OpenApiConfig;
// JSON-объект с обязательным полем name
OpenApiConfig::REQUEST_BODY => [
OpenApiConfig::REQUIRED => true,
OpenApiConfig::CONTENT => [
TypeConfig::CONTENT_TYPE_JSON => [
OpenApiConfig::SCHEMA => [
OpenApiConfig::TYPE => 'object',
OpenApiConfig::REQUIRED => [OpenApiConfig::NAME],
OpenApiConfig::PROPERTIES => [
'name' => [OpenApiConfig::TYPE => 'string', OpenApiConfig::EXAMPLE => 'Иван'],
],
],
],
],
],Параметры и ответы
| Что задано явно | Как применяется |
|---|---|
Параметр с теми же in и name | Заменяет совпавшее описание |
| Ответ с тем же HTTP-статусом | Дополняет или переопределяет автоматическое описание |
Собственный успешный ответ 2xx | Убирает автоматический успешный статус, если его нет в заданном списке |
use Native\Api\Config\Internals\OpenApiConfig;
// Описание ответов; фактический HTTP-статус задаёт контроллер
OpenApiConfig::RESPONSES => [
'201' => [OpenApiConfig::DESCRIPTION => 'Заказ создан'],
'400' => [OpenApiConfig::DESCRIPTION => 'Ошибка параметров запроса'],
],Именованные схемы
Из components поддерживается schemas. При совпадении имени применяется последнее описание.
use Native\Api\Config\Internals\OpenApiConfig;
// Общая схема заказа
OpenApiConfig::COMPONENTS => [
OpenApiConfig::SCHEMAS => [
'Order' => [
OpenApiConfig::TYPE => 'object',
OpenApiConfig::PROPERTIES => [
'id' => [OpenApiConfig::TYPE => 'integer'],
],
],
],
],use Native\Api\Config\Internals\OpenApiConfig;
// Ссылка на схему в описании тела запроса или ответа
OpenApiConfig::SCHEMA => [OpenApiConfig::REF => '#/components/schemas/Order'],Общие схемы ответа
OpenApiSchemas формирует описания ответов с техническими полями модуля. Имена схем перечислены в справочнике OpenApiConfig.
successResponse
Описание JSON-ответа с техническим конвертом
use Native\Api\Config\Internals\OpenApiConfig;
use Native\Api\Http\Docs\OpenApiSchemas;
OpenApiSchemas::successResponse(
description: 'Заказ получен',
resultSchema: [OpenApiConfig::TYPE => 'object'],
);Необязательные параметры: resultSchema — схема результата, example — пример полного ответа
errorResponse
Описание JSON-ошибки с кодами и примером
use Native\Api\Config\Internals\HttpStatusConfig;
use Native\Api\Config\Internals\ExceptionConfig;
use Native\Api\Http\Docs\OpenApiSchemas;
OpenApiSchemas::errorResponse(
statusCode: HttpStatusConfig::HTTP_STATUS_404,
description: 'Роут не найден',
errorCodes: [ExceptionConfig::ERROR_ROUTE_NOT_FOUND],
);Для ответа без технических полей задайте схему явно вместо OpenApiSchemas::successResponse().
Ссылка на схему
use Native\Api\Config\Internals\OpenApiConfig;
use Native\Api\Http\Docs\OpenApiSchemas;
$schema = OpenApiSchemas::ref(OpenApiConfig::SCHEMA_RESPONSE_ERROR);Метод возвращает массив с $ref на именованную схему.
requestBody, responses, callbacks и схемы влияют только на документацию. Полная карта — в разделе «Пример карты».