From cb7e2e19b96c6b1118c1f9cc167981c86c79382f Mon Sep 17 00:00:00 2001 From: Skripchenko Denis Date: Mon, 26 Oct 2026 20:56:03 +0300 Subject: [PATCH] docs: use getSchemaTemplates / getSecuritySchemes The documentation (en/ru/zh/de), the BaseApi docblocks and the api:lint hints switch to the neutral hook names; the earlier names keep working and are described as such. The IDE plugin reads both from 1.1.0. Test fixtures keep the earlier names on purpose. The lint snapshot of the broken fixture changes in its five hints only. Co-Authored-By: Claude Opus 5.5 --- .claude/CLAUDE.md | 6 +-- CHANGELOG.md | 9 +++++ README.md | 10 ++--- docs/de/README.md | 10 ++--- docs/de/cookbook.md | 6 +-- docs/de/docblock-tags.md | 10 ++--- docs/en/cookbook.md | 6 +-- docs/en/docblock-tags.md | 10 ++--- docs/ru/README.md | 10 ++--- docs/ru/cookbook.md | 6 +-- docs/ru/docblock-tags.md | 10 ++--- docs/zh/README.md | 10 ++--- docs/zh/cookbook.md | 6 +-- docs/zh/docblock-tags.md | 10 ++--- src/Components/BaseApi.php | 40 ++++++++++--------- src/Services/Linter/OpenApiLinter.php | 8 ++-- ...sts_Fixtures_Linter_BrokenApi____v1__.snap | 10 ++--- 17 files changed, 95 insertions(+), 82 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 6d1fc3d..2facb78 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -173,7 +173,7 @@ class ApiV1_1 extends ApiV1 { */ ``` -**Templates** are enabled via `$useResponseTemplates = true` on the Api class. `getSchemaTemplates()` / `getSecuritySchemes()` are the neutral names of `getOpenApiTemplates()` / `getOpenApiSecurityDefinitions()`: package code calls the neutral ones (which default to the old ones); users may override either. Keep docs examples on the old names until the IDE plugin (`../laravel-api-idea`, hardcodes the old names in TemplateLookup/TemplateUsages/SecurityLookup/CreateTemplateFix) supports the new ones. +**Templates** are enabled via `$useResponseTemplates = true` on the Api class. Templates and security schemes are declared in `getSchemaTemplates()` / `getSecuritySchemes()` (since 6.1); `getOpenApiTemplates()` / `getOpenApiSecurityDefinitions()` are their earlier names and keep working — package code calls the new ones, which default to the old ones. Docs and lint hints use the new names; test fixtures keep the old ones on purpose (they cover the fallback). The IDE plugin (`../laravel-api-idea`) reads both since 1.1.0 (`ApiHooks`). Shorthand string syntax (recommended): ``` @@ -191,7 +191,7 @@ Both shorthand and array formats can be mixed in the same template. class Api extends BaseApi { public static bool $useResponseTemplates = true; - public static function getOpenApiTemplates(): array { + public static function getSchemaTemplates(): array { return [ // Shorthand syntax 'UserResponse' => [ @@ -207,7 +207,7 @@ class Api extends BaseApi { ]; } - public static function getOpenApiSecurityDefinitions(): array { + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ 'type' => 'apiKey', diff --git a/CHANGELOG.md b/CHANGELOG.md index 7531448..07a764b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Changed + +- The documentation and the `api:lint` hints use `getSchemaTemplates()` and + `getSecuritySchemes()`. `getOpenApiTemplates()` and + `getOpenApiSecurityDefinitions()` keep working; the IDE plugin reads both + names from 1.1.0. + ## [6.1.0] — 2026-10-26 The API is now read through one model of its operations: `getMethods()` in one diff --git a/README.md b/README.md index b410364..aa4849f 100644 --- a/README.md +++ b/README.md @@ -371,7 +371,7 @@ Enable reusable schemas via `components/schemas`: class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array { + public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', // required integer @@ -394,7 +394,7 @@ class Api extends BaseApi { ]; } - public static function getOpenApiSecurityDefinitions(): array { + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => ['type' => 'apiKey', 'name' => 'Authorization', 'in' => 'header'], ]; @@ -402,7 +402,7 @@ class Api extends BaseApi { } ``` -**Neutral names.** `getSchemaTemplates()` and `getSecuritySchemes()` are the same hooks under names that are not about OpenAPI — the templates describe payloads whatever carries them. Override either name; the package reads the neutral one, which answers with the OpenAPI-era hook unless overridden itself. The examples here keep the OpenAPI-era names until the [IDE plugin](#ide-support) reads the neutral ones too. +**Names before 6.1.** `getOpenApiTemplates()` and `getOpenApiSecurityDefinitions()` keep working: they are the same hooks under their earlier names. Override either name; the package reads `getSchemaTemplates()` / `getSecuritySchemes()`, which answer with the earlier ones unless overridden themselves. The [IDE plugin](#ide-support) reads both names from 1.1.0. **Shorthand syntax reference:** @@ -703,7 +703,7 @@ publish that for Community. writes the tag from it — `email` becomes `string(email)`, a rule that is not `required` becomes optional, `in:a,b` becomes an enumeration. - Marks a `@response` template or a `@security` scheme nothing declares, and - offers to declare the template — creating `getOpenApiTemplates()` when the + offers to declare the template — creating `getSchemaTemplates()` when the class has none. - Turns the silent 404 red: an action pointing at a missing, non-public or static method is an error while typing, with a quick fix that writes the @@ -981,7 +981,7 @@ Dskripchenko\LaravelApi\Middlewares\RequestIdMiddleware::class | Class | Methods | |-------|---------| -| `BaseApi` (all methods are `static`) | `getMethods()`, `make()`, `getOpenApiTemplates()` / `getSchemaTemplates()`, `getOpenApiSecurityDefinitions()` / `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | +| `BaseApi` (all methods are `static`) | `getMethods()`, `make()`, `getSchemaTemplates()`, `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | | `BaseModule` | `getApi($version)`, `makeApi()`, `getApiVersionList()`, `getApiPrefix()`, `getApiUriPattern()`, `getAvailableApiMethods()`, `getDocMiddleware()` | | `Meta` | `string($key, $name)`, `integer($key, $name)`, `number($key, $name)`, `boolean($key, $name)`, `hidden($key, $name)`, `select($key, $name, $items)`, `file($key, $name, $src)`, `action($key, $condition)`, `crud()`, `getOpenApiInputs()`, `getColumnKeys()` | diff --git a/docs/de/README.md b/docs/de/README.md index cf98ed7..01b7060 100644 --- a/docs/de/README.md +++ b/docs/de/README.md @@ -366,7 +366,7 @@ Wiederverwendbare Schemas aktivieren über `components/schemas`: class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array { + public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', // Pflichtfeld Integer @@ -380,7 +380,7 @@ class Api extends BaseApi { ]; } - public static function getOpenApiSecurityDefinitions(): array { + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => ['type' => 'apiKey', 'name' => 'Authorization', 'in' => 'header'], ]; @@ -388,7 +388,7 @@ class Api extends BaseApi { } ``` -**Neutrale Namen.** `getSchemaTemplates()` und `getSecuritySchemes()` sind dieselben Hooks unter Namen, die nicht an OpenAPI hängen — Templates beschreiben Payloads, egal wodurch sie übertragen werden. Überschreiben Sie einen der beiden Namen; das Paket liest den neutralen, der ohne eigene Überschreibung den alten Hook beantwortet. Die Beispiele hier bleiben bei den alten Namen, bis das IDE-Plugin die neutralen ebenfalls liest. +**Namen vor 6.1.** `getOpenApiTemplates()` und `getOpenApiSecurityDefinitions()` funktionieren weiter: Es sind dieselben Hooks unter ihren früheren Namen. Überschreiben Sie einen der beiden Namen; das Paket liest `getSchemaTemplates()` / `getSecuritySchemes()`, die ohne eigene Überschreibung die früheren beantworten. Das IDE-Plugin liest ab 1.1.0 beide Namen. **Shorthand-Syntax:** `type` — optional, `type!` — Pflicht, `type(format)` — mit Format, `@Model` — Referenz, `@Model[]` — Array von Referenzen. Das Array-Format (`['type' => '...', 'required' => true]`) wird ebenfalls unterstützt. @@ -801,7 +801,7 @@ das veröffentlicht JetBrains für Community nicht. ohne `required` → optionales Feld, `in:a,b` → Aufzählung. - Markiert ein `@response`-Template oder ein `@security`-Schema, das niemand deklariert hat, und bietet an, das Template zu deklarieren — inklusive - `getOpenApiTemplates()`, wenn die Klasse keines hat. + `getSchemaTemplates()`, wenn die Klasse keines hat. - Macht den stillen 404 rot: eine Action, die auf eine fehlende, nicht öffentliche oder statische Methode zeigt, ist ein Fehler beim Tippen, mit einem Quick-Fix, der die Methode nach dem Vorbild der Nachbarn schreibt. @@ -936,7 +936,7 @@ das veröffentlicht JetBrains für Community nicht. | Klasse | Methoden | |-------|---------| -| `BaseApi` | `getMethods()`, `make()`, `getOpenApiTemplates()` / `getSchemaTemplates()`, `getOpenApiSecurityDefinitions()` / `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | +| `BaseApi` | `getMethods()`, `make()`, `getSchemaTemplates()`, `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | | `BaseModule` | `getApi($version)`, `makeApi()`, `getApiVersionList()`, `getApiPrefix()`, `getApiUriPattern()`, `getAvailableApiMethods()` | | `Meta` | `string()`, `integer()`, `number()`, `boolean()`, `hidden()`, `select()`, `file()`, `action()`, `crud()`, `getOpenApiInputs()`, `getColumnKeys()` | diff --git a/docs/de/cookbook.md b/docs/de/cookbook.md index 3e9e215..568e14d 100644 --- a/docs/de/cookbook.md +++ b/docs/de/cookbook.md @@ -374,7 +374,7 @@ class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array + public static function getSchemaTemplates(): array { return [ 'UserResponse' => [ @@ -389,7 +389,7 @@ class Api extends BaseApi ]; } - public static function getOpenApiSecurityDefinitions(): array + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ @@ -556,7 +556,7 @@ export interface UserShowOutput { | `$ref` | Interface-Name | | `enum` | `'a' \| 'b' \| 'c'` | -Komponentenschemata aus `getOpenApiTemplates()` werden als benannte Interfaces generiert. Fuer jede Operation werden `{Controller}{Action}Input`- und `{Controller}{Action}Output`-Typen erstellt. +Komponentenschemata aus `getSchemaTemplates()` werden als benannte Interfaces generiert. Fuer jede Operation werden `{Controller}{Action}Input`- und `{Controller}{Action}Output`-Typen erstellt. --- diff --git a/docs/de/docblock-tags.md b/docs/de/docblock-tags.md index 6aebfd7..765e3c6 100644 --- a/docs/de/docblock-tags.md +++ b/docs/de/docblock-tags.md @@ -110,7 +110,7 @@ Erzeugt: @input @OrderCreateRequest ``` -Erzeugt `$ref: '#/components/schemas/OrderCreateRequest'` im requestBody. Das Modell muss in `getOpenApiTemplates()` definiert sein. +Erzeugt `$ref: '#/components/schemas/OrderCreateRequest'` im requestBody. Das Modell muss in `getSchemaTemplates()` definiert sein. ### Liste von Skalaren @@ -316,10 +316,10 @@ Wendet ein Sicherheitsschema auf die Operation an. @security BearerAuth ``` -Das Schema muss in `getOpenApiSecurityDefinitions()` der Api-Klasse definiert sein: +Das Schema muss in `getSecuritySchemes()` der Api-Klasse definiert sein: ```php -public static function getOpenApiSecurityDefinitions(): array { +public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ 'type' => 'apiKey', @@ -384,7 +384,7 @@ Setzt einen Beispielwert fuer einen Parameter. ## Kurzschreibweise fuer Templates -Bei der Definition von Templates in `getOpenApiTemplates()` kann eine Kurzschreibweise als String anstelle von ausfuehrlichen Arrays verwendet werden: +Bei der Definition von Templates in `getSchemaTemplates()` kann eine Kurzschreibweise als String anstelle von ausfuehrlichen Arrays verwendet werden: | Syntax | Bedeutung | Aequivalentes Array | |--------|---------|------------------| @@ -403,7 +403,7 @@ Bei der Definition von Templates in `getOpenApiTemplates()` kann eine Kurzschrei ### Beispiel ```php -public static function getOpenApiTemplates(): array { +public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', diff --git a/docs/en/cookbook.md b/docs/en/cookbook.md index bc75abe..4908228 100644 --- a/docs/en/cookbook.md +++ b/docs/en/cookbook.md @@ -374,7 +374,7 @@ class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array + public static function getSchemaTemplates(): array { return [ 'UserResponse' => [ @@ -389,7 +389,7 @@ class Api extends BaseApi ]; } - public static function getOpenApiSecurityDefinitions(): array + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ @@ -556,7 +556,7 @@ export interface UserShowOutput { | `$ref` | Interface name | | `enum` | `'a' \| 'b' \| 'c'` | -Component schemas from `getOpenApiTemplates()` are generated as named interfaces. Each operation produces `{Controller}{Action}Input` and `{Controller}{Action}Output` types. +Component schemas from `getSchemaTemplates()` are generated as named interfaces. Each operation produces `{Controller}{Action}Input` and `{Controller}{Action}Output` types. --- diff --git a/docs/en/docblock-tags.md b/docs/en/docblock-tags.md index b60bcb6..fb0c211 100644 --- a/docs/en/docblock-tags.md +++ b/docs/en/docblock-tags.md @@ -110,7 +110,7 @@ Generates: @input @OrderCreateRequest ``` -Generates `$ref: '#/components/schemas/OrderCreateRequest'` in requestBody. The model must be defined in `getOpenApiTemplates()`. +Generates `$ref: '#/components/schemas/OrderCreateRequest'` in requestBody. The model must be defined in `getSchemaTemplates()`. ### List of scalars @@ -314,10 +314,10 @@ Applies a security scheme to the operation. @security BearerAuth ``` -The scheme must be defined in `getOpenApiSecurityDefinitions()` on the Api class: +The scheme must be defined in `getSecuritySchemes()` on the Api class: ```php -public static function getOpenApiSecurityDefinitions(): array { +public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ 'type' => 'apiKey', @@ -382,7 +382,7 @@ Sets an example value for a parameter. ## Template shorthand syntax -When defining templates in `getOpenApiTemplates()`, you can use a shorthand string notation instead of verbose arrays: +When defining templates in `getSchemaTemplates()`, you can use a shorthand string notation instead of verbose arrays: | Syntax | Meaning | Equivalent array | |--------|---------|------------------| @@ -401,7 +401,7 @@ When defining templates in `getOpenApiTemplates()`, you can use a shorthand stri ### Example ```php -public static function getOpenApiTemplates(): array { +public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', diff --git a/docs/ru/README.md b/docs/ru/README.md index 3c6f9f1..9f17570 100644 --- a/docs/ru/README.md +++ b/docs/ru/README.md @@ -365,7 +365,7 @@ Schema, который попадает в спецификацию как ес class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array { + public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', // обязательное целое @@ -379,7 +379,7 @@ class Api extends BaseApi { ]; } - public static function getOpenApiSecurityDefinitions(): array { + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => ['type' => 'apiKey', 'name' => 'Authorization', 'in' => 'header'], ]; @@ -387,7 +387,7 @@ class Api extends BaseApi { } ``` -**Нейтральные имена.** `getSchemaTemplates()` и `getSecuritySchemes()` — те же хуки под именами, не привязанными к OpenAPI: шаблоны описывают payload, чем бы он ни передавался. Переопределяйте любое из имён; пакет читает нейтральное, а оно, если не переопределено, отвечает старым хуком. Примеры здесь остаются на старых именах, пока их не начнёт читать [IDE-плагин](#поддержка-ide). +**Имена до 6.1.** `getOpenApiTemplates()` и `getOpenApiSecurityDefinitions()` продолжают работать: это те же хуки под прежними именами. Переопределяйте любое из имён; пакет читает `getSchemaTemplates()` / `getSecuritySchemes()`, а они, если не переопределены, отвечают прежними. [IDE-плагин](#поддержка-ide) читает оба имени начиная с 1.1.0. **Shorthand-синтаксис:** `type` — необязательное, `type!` — обязательное, `type(format)` — с форматом, `@Model` — ссылка, `@Model[]` — массив ссылок. Также поддерживается формат массивов (`['type' => '...', 'required' => true]`). @@ -810,7 +810,7 @@ PhpStorm или IntelliJ IDEA Ultimate с плагином PHP. IDEA Community из него: `email` → `string(email)`, правило без `required` → необязательное поле, `in:a,b` → перечисление. - Отмечает шаблон `@response` или схему `@security`, которых никто не объявлял, - и предлагает объявить шаблон — заведя `getOpenApiTemplates()`, если метода нет. + и предлагает объявить шаблон — заведя `getSchemaTemplates()`, если метода нет. - Делает молчаливую 404 красной: действие, указывающее на отсутствующий, непубличный или статический метод, — ошибка прямо при наборе, с быстрым исправлением, которое пишет метод по образцу соседей. @@ -944,7 +944,7 @@ PhpStorm или IntelliJ IDEA Ultimate с плагином PHP. IDEA Community | Класс | Методы | |-------|---------| -| `BaseApi` | `getMethods()`, `make()`, `getOpenApiTemplates()` / `getSchemaTemplates()`, `getOpenApiSecurityDefinitions()` / `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | +| `BaseApi` | `getMethods()`, `make()`, `getSchemaTemplates()`, `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | | `BaseModule` | `getApi($version)`, `makeApi()`, `getApiVersionList()`, `getApiPrefix()`, `getApiUriPattern()`, `getAvailableApiMethods()` | | `Meta` | `string()`, `integer()`, `number()`, `boolean()`, `hidden()`, `select()`, `file()`, `action()`, `crud()`, `getOpenApiInputs()`, `getColumnKeys()` | diff --git a/docs/ru/cookbook.md b/docs/ru/cookbook.md index 8f59917..7d8de9e 100644 --- a/docs/ru/cookbook.md +++ b/docs/ru/cookbook.md @@ -374,7 +374,7 @@ class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array + public static function getSchemaTemplates(): array { return [ 'UserResponse' => [ @@ -389,7 +389,7 @@ class Api extends BaseApi ]; } - public static function getOpenApiSecurityDefinitions(): array + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ @@ -556,7 +556,7 @@ export interface UserShowOutput { | `$ref` | Имя интерфейса | | `enum` | `'a' \| 'b' \| 'c'` | -Схемы компонентов из `getOpenApiTemplates()` генерируются как именованные интерфейсы. Для каждой операции создаются типы `{Controller}{Action}Input` и `{Controller}{Action}Output`. +Схемы компонентов из `getSchemaTemplates()` генерируются как именованные интерфейсы. Для каждой операции создаются типы `{Controller}{Action}Input` и `{Controller}{Action}Output`. --- diff --git a/docs/ru/docblock-tags.md b/docs/ru/docblock-tags.md index 2426378..4acb5fc 100644 --- a/docs/ru/docblock-tags.md +++ b/docs/ru/docblock-tags.md @@ -110,7 +110,7 @@ @input @OrderCreateRequest ``` -Генерирует `$ref: '#/components/schemas/OrderCreateRequest'` в requestBody. Модель должна быть определена в `getOpenApiTemplates()`. +Генерирует `$ref: '#/components/schemas/OrderCreateRequest'` в requestBody. Модель должна быть определена в `getSchemaTemplates()`. ### Список скаляров @@ -314,10 +314,10 @@ public function entityFields(OperationContext $context): array @security BearerAuth ``` -Схема должна быть определена в `getOpenApiSecurityDefinitions()` класса Api: +Схема должна быть определена в `getSecuritySchemes()` класса Api: ```php -public static function getOpenApiSecurityDefinitions(): array { +public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ 'type' => 'apiKey', @@ -382,7 +382,7 @@ public static function getOpenApiSecurityDefinitions(): array { ## Сокращённый синтаксис шаблонов -При определении шаблонов в `getOpenApiTemplates()` можно использовать сокращённую строковую нотацию вместо подробных массивов: +При определении шаблонов в `getSchemaTemplates()` можно использовать сокращённую строковую нотацию вместо подробных массивов: | Синтаксис | Значение | Эквивалентный массив | |--------|---------|------------------| @@ -401,7 +401,7 @@ public static function getOpenApiSecurityDefinitions(): array { ### Пример ```php -public static function getOpenApiTemplates(): array { +public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', diff --git a/docs/zh/README.md b/docs/zh/README.md index 0f75ed6..d003653 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -359,7 +359,7 @@ public function entityFields(OperationContext $context): array class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array { + public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', // 必填整数 @@ -373,7 +373,7 @@ class Api extends BaseApi { ]; } - public static function getOpenApiSecurityDefinitions(): array { + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => ['type' => 'apiKey', 'name' => 'Authorization', 'in' => 'header'], ]; @@ -381,7 +381,7 @@ class Api extends BaseApi { } ``` -**中性名称。** `getSchemaTemplates()` 和 `getSecuritySchemes()` 是同样的钩子，只是名称与 OpenAPI 无关——模板描述的是负载，无论由什么传输。可以重写其中任意一个；本包读取中性名称，若未重写则返回旧钩子的结果。在 IDE 插件支持中性名称之前，这里的示例仍使用旧名称。 +**6.1 之前的名称。** `getOpenApiTemplates()` 和 `getOpenApiSecurityDefinitions()` 仍然有效：它们是同样的钩子，只是旧名称。可以重写其中任意一个；本包读取 `getSchemaTemplates()` / `getSecuritySchemes()`，若未重写则返回旧名称的结果。IDE 插件从 1.1.0 起同时识别两种名称。 **简写语法：** `type` — 可选，`type!` — 必填，`type(format)` — 带格式，`@Model` — 引用，`@Model[]` — 引用数组。数组格式（`['type' => '...', 'required' => true]`）同样支持。 @@ -765,7 +765,7 @@ https://raw.githubusercontent.com/dskripchenko/laravel-api-idea/main/updatePlugi 上报出，并提供从规则写出标签的快速修复：`email` → `string(email)`，没有 `required` 的规则 → 可选字段，`in:a,b` → 枚举。 - 标出无人声明的 `@response` 模板或 `@security` 方案，并提议声明该模板——类中没有 - `getOpenApiTemplates()` 时一并创建。 + `getSchemaTemplates()` 时一并创建。 - 让静默的 404 变红：指向缺失、非公开或静态方法的 action 在输入时即为错误，快速修复 会按邻近方法的样子写出该方法。 - 补全类型、格式、模板名、安全方案和状态码。 @@ -895,7 +895,7 @@ https://raw.githubusercontent.com/dskripchenko/laravel-api-idea/main/updatePlugi | 类 | 方法 | |----|------| -| `BaseApi` | `getMethods()`, `make()`, `getOpenApiTemplates()` / `getSchemaTemplates()`, `getOpenApiSecurityDefinitions()` / `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | +| `BaseApi` | `getMethods()`, `make()`, `getSchemaTemplates()`, `getSecuritySchemes()`, `operations()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | | `BaseModule` | `getApi($version)`, `makeApi()`, `getApiVersionList()`, `getApiPrefix()`, `getApiUriPattern()`, `getAvailableApiMethods()` | | `Meta` | `string()`, `integer()`, `number()`, `boolean()`, `hidden()`, `select()`, `file()`, `action()`, `crud()`, `getOpenApiInputs()`, `getColumnKeys()` | diff --git a/docs/zh/cookbook.md b/docs/zh/cookbook.md index 15fa6b2..f4b492f 100644 --- a/docs/zh/cookbook.md +++ b/docs/zh/cookbook.md @@ -374,7 +374,7 @@ class Api extends BaseApi { public static $useResponseTemplates = true; - public static function getOpenApiTemplates(): array + public static function getSchemaTemplates(): array { return [ 'UserResponse' => [ @@ -389,7 +389,7 @@ class Api extends BaseApi ]; } - public static function getOpenApiSecurityDefinitions(): array + public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ @@ -556,7 +556,7 @@ export interface UserShowOutput { | `$ref` | 接口名称 | | `enum` | `'a' \| 'b' \| 'c'` | -`getOpenApiTemplates()` 中的组件 schema 会生成为命名接口。每个操作会生成 `{Controller}{Action}Input` 和 `{Controller}{Action}Output` 类型。 +`getSchemaTemplates()` 中的组件 schema 会生成为命名接口。每个操作会生成 `{Controller}{Action}Input` 和 `{Controller}{Action}Output` 类型。 --- diff --git a/docs/zh/docblock-tags.md b/docs/zh/docblock-tags.md index 14e9e02..088ae0c 100644 --- a/docs/zh/docblock-tags.md +++ b/docs/zh/docblock-tags.md @@ -110,7 +110,7 @@ @input @OrderCreateRequest ``` -在 requestBody 中生成 `$ref: '#/components/schemas/OrderCreateRequest'`。该模型必须在 `getOpenApiTemplates()` 中定义。 +在 requestBody 中生成 `$ref: '#/components/schemas/OrderCreateRequest'`。该模型必须在 `getSchemaTemplates()` 中定义。 ### 标量列表 @@ -309,10 +309,10 @@ schema，合并到其他 `@output` 行之上。`@output {Template}` 行仍然优 @security BearerAuth ``` -该方案必须在 Api 类的 `getOpenApiSecurityDefinitions()` 中定义： +该方案必须在 Api 类的 `getSecuritySchemes()` 中定义： ```php -public static function getOpenApiSecurityDefinitions(): array { +public static function getSecuritySchemes(): array { return [ 'BearerAuth' => [ 'type' => 'apiKey', @@ -377,7 +377,7 @@ public static function getOpenApiSecurityDefinitions(): array { ## 模板简写语法 -在 `getOpenApiTemplates()` 中定义模板时，可以使用简写字符串表示法代替冗长的数组： +在 `getSchemaTemplates()` 中定义模板时，可以使用简写字符串表示法代替冗长的数组： | 语法 | 含义 | 等效数组 | |--------|---------|------------------| @@ -396,7 +396,7 @@ public static function getOpenApiSecurityDefinitions(): array { ### 示例 ```php -public static function getOpenApiTemplates(): array { +public static function getSchemaTemplates(): array { return [ 'OrderResponse' => [ 'id' => 'integer!', diff --git a/src/Components/BaseApi.php b/src/Components/BaseApi.php index 26d3c99..4fefdd4 100644 --- a/src/Components/BaseApi.php +++ b/src/Components/BaseApi.php @@ -37,24 +37,7 @@ public static function getMethods(): array } /** - * [ - * 'User' => [ - * 'id' => [ - * 'type' => 'integer', - * 'required' => true, - * ], - * 'name' => [ - * 'type' => 'string', - * 'required' => true, - * ], - * ], - * 'Users' => [ - * 'list' => [ - * 'type' => 'array', - * 'items' => '@User' - * ] - * ] - * ]; + * The templates under their name before 6.1 — {@see getSchemaTemplates()}. * * @return array */ @@ -64,6 +47,8 @@ public static function getOpenApiTemplates(): array } /** + * The security schemes under their name before 6.1 — {@see getSecuritySchemes()}. + * * @return array */ public static function getOpenApiSecurityDefinitions(): array @@ -79,6 +64,25 @@ public static function getOpenApiSecurityDefinitions(): array * Override either one. The package reads this one, which answers with * getOpenApiTemplates() unless it is overridden itself. * + * [ + * 'User' => [ + * 'id' => [ + * 'type' => 'integer', + * 'required' => true, + * ], + * 'name' => [ + * 'type' => 'string', + * 'required' => true, + * ], + * ], + * 'Users' => [ + * 'list' => [ + * 'type' => 'array', + * 'items' => '@User' + * ] + * ] + * ]; + * * @return array */ public static function getSchemaTemplates(): array diff --git a/src/Services/Linter/OpenApiLinter.php b/src/Services/Linter/OpenApiLinter.php index 8066dd0..047b1f2 100644 --- a/src/Services/Linter/OpenApiLinter.php +++ b/src/Services/Linter/OpenApiLinter.php @@ -483,7 +483,7 @@ private function lintActionSecurity(string $where, array $security, array $secur 'security.unknown-scheme', $where, "The action asks for the security scheme `{$name}`, which is not defined.", - 'Add it to getOpenApiSecurityDefinitions() on the Api class.' + 'Add it to getSecuritySchemes() on the Api class.' ); } } @@ -572,7 +572,7 @@ private function lintParameterTags( 'tag.unknown-template', $where, "@{$tagName} refers to the template `{$parts['model']}`, which is not defined.", - 'Add it to getOpenApiTemplates(), or the spec gets a $ref pointing nowhere.' + 'Add it to getSchemaTemplates(), or the spec gets a $ref pointing nowhere.' ); } @@ -744,7 +744,7 @@ private function lintResponseTags(string $where, OperationDoc $doc, array $templ 'response.unknown-template', $where, "@response {$code} {{$template}} refers to a template that is not defined.", - 'Add it to getOpenApiTemplates() on the Api class.' + 'Add it to getSchemaTemplates() on the Api class.' ); } } @@ -766,7 +766,7 @@ private function lintSecurityTags(string $where, OperationDoc $doc, array $secur 'security.unknown-scheme', $where, "@security {$name} — no such scheme is defined.", - 'Add it to getOpenApiSecurityDefinitions() on the Api class.' + 'Add it to getSecuritySchemes() on the Api class.' ); } } diff --git a/tests/.pest/snapshots/Feature/GoldenMaster/GoldenMasterTest/it_keeps_the_lint_report_with_data_set__dataset__lint_broken_____Tests_Fixtures_Linter_BrokenApi____v1__.snap b/tests/.pest/snapshots/Feature/GoldenMaster/GoldenMasterTest/it_keeps_the_lint_report_with_data_set__dataset__lint_broken_____Tests_Fixtures_Linter_BrokenApi____v1__.snap index c1f6597..6a2094d 100644 --- a/tests/.pest/snapshots/Feature/GoldenMaster/GoldenMasterTest/it_keeps_the_lint_report_with_data_set__dataset__lint_broken_____Tests_Fixtures_Linter_BrokenApi____v1__.snap +++ b/tests/.pest/snapshots/Feature/GoldenMaster/GoldenMasterTest/it_keeps_the_lint_report_with_data_set__dataset__lint_broken_____Tests_Fixtures_Linter_BrokenApi____v1__.snap @@ -32,28 +32,28 @@ "rule": "tag.unknown-template", "where": "v1 · broken.danglingRefs", "message": "@input refers to the template `MissingRequest`, which is not defined.", - "hint": "Add it to getOpenApiTemplates(), or the spec gets a $ref pointing nowhere." + "hint": "Add it to getSchemaTemplates(), or the spec gets a $ref pointing nowhere." }, { "severity": "error", "rule": "tag.unknown-template", "where": "v1 · broken.danglingRefs", "message": "@output refers to the template `MissingModel`, which is not defined.", - "hint": "Add it to getOpenApiTemplates(), or the spec gets a $ref pointing nowhere." + "hint": "Add it to getSchemaTemplates(), or the spec gets a $ref pointing nowhere." }, { "severity": "error", "rule": "response.unknown-template", "where": "v1 · broken.danglingRefs", "message": "@response 404 {MissingTemplate} refers to a template that is not defined.", - "hint": "Add it to getOpenApiTemplates() on the Api class." + "hint": "Add it to getSchemaTemplates() on the Api class." }, { "severity": "error", "rule": "security.unknown-scheme", "where": "v1 · broken.danglingRefs", "message": "@security MissingScheme — no such scheme is defined.", - "hint": "Add it to getOpenApiSecurityDefinitions() on the Api class." + "hint": "Add it to getSecuritySchemes() on the Api class." }, { "severity": "error", @@ -151,7 +151,7 @@ "rule": "security.unknown-scheme", "where": "v1 · broken.ghostSecurity", "message": "The action asks for the security scheme `GhostScheme`, which is not defined.", - "hint": "Add it to getOpenApiSecurityDefinitions() on the Api class." + "hint": "Add it to getSecuritySchemes() on the Api class." }, { "severity": "warning",