PHPackages                             on1kel/oas-builder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. on1kel/oas-builder

ActiveLibrary

on1kel/oas-builder
==================

OpenAPI Specification Builder: Fluent-DSL библиотека для сборки спецификаций OpenAPI

v1.0.4(4mo ago)164↓50%1MITPHPPHP ^8.2

Since Oct 24Pushed 4mo agoCompare

[ Source](https://github.com/on1kel/oas-builder)[ Packagist](https://packagist.org/packages/on1kel/oas-builder)[ RSS](/packages/on1kel-oas-builder/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (7)Versions (6)Used By (1)

on1kel/oas-builder
==================

[](#on1keloas-builder)

**OpenAPI Specification Builder** — это набор иммутабельных PHP-билдеров (fluent DSL), которые позволяют собрать спецификацию OpenAPI (3.1 / 3.2) программно, без ручного YAML/JSON.

Билдеры возвращают строго типизированные объекты ядра (`on1kel/oas-core`), которые дальше можно сериализовать в JSON/YAML и отдавать в документацию, Swagger UI, генераторы клиентов и т.д.

---

Ключевые особенности
--------------------

[](#ключевые-особенности)

### 1. Fluent-DSL поверх OAS 3.1 / 3.2

[](#1-fluent-dsl-поверх-oas-31--32)

```
OpenApi::create()
    ->oas31()
    ->info(
        Info::of('My API', '1.0.0')
    )
    ->paths(
        Paths::of()
            ->get('/users/{id}', $getUserOp)
    )
    ->components(
        Components::create()
            ->schema('User', $userSchema)
    )
    ->toModel(); // -> Core\OpenApiDocument
```

### 2. Иммутабельность

[](#2-иммутабельность)

Каждый вызов сеттера возвращает НОВЫЙ объект. Никаких "мутаций по месту", значит удобно переиспользовать и дополнять билдеры без побочных эффектов.

```
$infoV1 = Info::of('Shop API', '1.0.0');
$infoV2 = $infoV1->version('2.0.0'); // $infoV1 не изменился
```

### 3. Жёсткие инварианты и валидация

[](#3-жёсткие-инварианты-и-валидация)

- Обязательные поля проверяются (например, `openapi`, `info`, `Response::description()` и т.д.).
- Взаимоисключающие поля проверяются (например, `MediaType::example()` нельзя вместе с `MediaType::examples()`).
- Несовместимые с профилем спецификации поля блокируются (`FeatureGuard`).

### 4. Профили спецификации (Profile)

[](#4-профили-спецификации-profile)

Профиль = знание того, какие фичи разрешены для конкретной версии спецификации (3.1 против 3.2):

- какие поля вообще допустимы,
- какие секции доступны (`webhooks`, `jsonSchemaDialect`, `itemSchema`, `tag.parent`, ...),
- какие ключи недоступны в текущем профиле → будет выброшено исключение.

Профиль хранится в `ProfileProvider` и автоматически прокидывается во ВСЕ билдеры.

```
use On1kel\OAS\Builder\Support\ProfileProvider;
// Пример: профиль OpenAPI 3.1 или 3.2
// ProfileProvider::setDefault(new OAS31Profile());
// ProfileProvider::setDefault(new OAS32Profile());
```

Если профиль не установлен явно, вызов билдеров упадёт с понятной ошибкой:

```
ProfileProvider: профиль не задан. Вызови ProfileProvider::setDefault(new OAS31Profile()|OAS32Profile()).

```

Пакет `on1kel/oas-profile-31` содержит реализацию профиля для OpenAPI 3.1 и описывает допустимые фичи этой версии.

### 5. Чёткое разделение "builder" → "core"

[](#5-чёткое-разделение-builder--core)

- Публичный код (вы пишете им) — билдеры из `On1kel\OAS\Builder\...`
- Результат сборки — строгие модели ядра (`On1kel\OAS\Core\Model\...`), которые возвращаются методом `toModel()`.

Билдер НИКОГДА не просит у вас готовые Core-модели (за редкими намеренно разрешёнными исключениями вроде `ExternalDocumentation`). В билдер передаются только:

- скаляры,
- билдеры,
- строки `$ref` (например `#/components/schemas/User`).

---

Установка
---------

[](#установка)

```
composer require on1kel/oas-builder
```

Пакет зависит от `on1kel/oas-core` (уже объявлено в `require`).

Для конкретной версии спецификации нужно добавить профиль. Для OpenAPI 3.1:

```
composer require on1kel/oas-profile-31
```

(Пакет `on1kel/oas-profile-31` объявляет профиль правил и фич для OAS 3.1 и используется `ProfileProvider`.)

Требования:

- PHP ^8.2
- ext-json (непосредственно ядру почти всегда нужен JSON)
- семантика пакета — SemVer (`^1.0`)

Лицензия: MIT.

---

Быстрый старт (полноценный пример)
----------------------------------

[](#быстрый-старт-полноценный-пример)

Ниже пример минимального документа c одним GET `/users/{id}`.

```