Download the PHP package on1kel/oas-builder without Composer

On this page you can find all versions of the php package on1kel/oas-builder. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package oas-builder

on1kel/oas-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

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

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

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

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

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

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

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

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

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

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


Установка

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

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

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

Требования:

Лицензия: MIT.


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

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

Что важно:


Архитектура пакета

1. Билдеры по секциям спецификации

Все билдеры реализуют общий контракт:

То есть любая часть дерева можно собрать отдельно и позже вклеить в документ.

2. CoreBridge

CoreBridge\Assembler и CoreBridge\RefFactory — технический слой между билдерами и моделью ядра:

Этот слой гарантирует, что на выходе toModel() вы всегда получаете корректные структуры on1kel/oas-core, а не случайные PHP-массивы.

3. FeatureGuard

Support\FeatureGuard получает ProfileContext и запрещает поля, которые недоступны в текущем профиле спецификации. Например, если поле itemSchema разрешено только в OAS 3.2, попытка вызвать соответствующий сеттер в профиле 3.1 кинет FeatureNotSupported.

Это:


Работа с $ref

Во многих местах билдеры принимают ИЛИ билдер, ИЛИ строку $ref.

Примеры:

Это сознательное решение:


Расширения (x-...)

Любой билдер с трейтом HasExtensions поддерживает vendor extensions:

->extension($name, $value) хранит произвольные данные, которые потом попадут в финальную core-модель.


Обработка результата (toModel())

Каждый билдер имеет метод toModel(), который собирает финальный экземпляр ядра on1kel/oas-core.

Примеры:

Дальше вы можете:

  1. сериализовать объект ядра в YAML/JSON (например, отдать в Swagger UI),
  2. использовать его в автогенерации клиентов/серверов,
  3. сохранить как артефакт CI.

Способ сериализации зависит от того, как именно on1kel/oas-core представляет модель (JsonSerializable, export-вспомогательные методы и т.д.). Если ваш рантайм ожидает массив — преобразуйте core-модель соответствующим методом ядра или собственным маппером. Структура уже нормализована и строгая (в том числе коллекции Map и List из ядра).


Инварианты и правила использования

  1. Иммутабельность. Любой сеттер (->summary(), ->description(), ->schema(), …) не изменяет текущий инстанс, а возвращает клон с изменениями.

  2. Только билдеры / $ref / скаляры. В публичных методах вы НЕ передаёте "готовые" Core-модели ядра напрямую. Исключения чётко помечены в коде комментариями (например ExternalDocumentation и т.п., где это оправдано).

  3. Взаимоисключающие поля. Некоторые поля по спецификации нельзя указывать одновременно. Пример: MediaType::example() конфликтует с MediaType::examples(). Попытка смешать — InvalidCombination.

  4. Обязательные поля. Если вы не установили поле, которое требуется спекой (например, OpenApi::info()), toModel() бросит RequiredMissing.

  5. Проверка профиля. Если поле недоступно для активного профиля спецификации, будет FeatureNotSupported.

  6. Валидация путей, кодов ответа и т.д. Paths::put('/users/{id}', ...) не позволит пустой путь, всегда требует ведущий /. Responses валидирует коды ('200', '404', 'default' и т.п.) и не даст положить мусор.

Когда использовать этот пакет

Подходит для:

Удобен в CI:


TL;DR

  1. Установи пакет и профиль (3.1 или 3.2).
  2. Вызови ProfileProvider::setDefault(...).
  3. Построй дерево через билдеры (OpenApi, Info, Paths, Operation, Responses, Schema, Components, …).
  4. Вызови ->toModel() и получи строгую модель ядра (Core\OpenApiDocument).
  5. Сериализуй в JSON/YAML как тебе нужно.

Пакет под лицензией MIT.


All versions of oas-builder with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
on1kel/oas-core Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package on1kel/oas-builder contains the following files

Loading the files please wait ...