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",