zircote/swagger-php 6.19.0

on PHP Packagist

Spec pipeline

An enum as a type

In hybrid and spec mode, an enum without an OA\Schema describes the property, parameter or request body it types. It becomes a schema named after the enum, and the type references it. Before, it was {}, with a warning that its type was left out. (#2302)

enum Language: string
{
    case English = 'en';
    case German = 'de';
}

#[OA\Schema]
class Book
{
    #[OA\Property]
    public Language $language;
}

Here language references a Language schema of type string with the values en and de. A backed enum lists its backing values, since that is what it serializes to. A bare OA\Schema on the enum still lists the case names. Enums in arrays, maps and nullable types count too, and a member with its own enum or ref is left as it is. Classic mode is unchanged.

All modes

• symfony/console accepts ^5.4, next to ^6.4, ^7.0 and ^8.0. Symfony 5.4 gets security fixes until February 2029. (#2306)

Output changes

Top-level key order

This changes hybrid and spec output. The document's top-level keys come in classic's order: openapi, info, servers, paths, components, security, tags, externalDocs, webhooks. Before, tags, security and externalDocs came before components, and webhooks straight after paths. A project moving from classic to hybrid no longer sees its committed document reordered on the first build. (#2309)

An enum as a type

This changes hybrid and spec output. A property, parameter or request body typed with an enum without a schema references a new schema named after the enum, instead of being {}. See above. (#2302)

An attribute without an operation

This changes spec output. A bare #[OA\Response] or #[OA\RequestBody] on a method without an operation of its own is dropped with a warning, wherever the method is declared. Before, it went into the operation of a method declared before it, and with two of those it was ambiguous and the whole class was skipped. The same holds between a method's parameters: one parameter's attribute does not nest into another's. (#2308)

Open ends of an int range

This changes output in every mode. positive-int and int<2, max> give only a minimum, and int<min, 10>, negative-int and non-positive-int only a maximum. Before, the open end was written as a 64-bit limit such as 9223372036854775807, which is no bound of the API, and above JavaScript's Number.MAX_SAFE_INTEGER. A closed range such as int<5, 25> is unchanged. (#2307)

A union with a class that has no schema

This changes output in every mode. A union with a member that is a class without a schema, for example Thing|int, is left untyped, as a property typed with the class alone is. Before, it was oneOf: [{type: integer}, {}]. {} matches any value, so an integer matched both members and oneOf rejected it. A union of components and native types keeps its oneOf. (#2304)

A class in a nested type

This changes classic output. Array items, map values, array shape members and union members typed with a class that is not a component are left untyped. Before, the class name was written as the type, for example items: { type: 'App\Thing' }, which is not a JSON Schema type. Classic now matches hybrid here. (#2303)

Documentation

• Every typed subclass in OpenApi\Spec, such as Parameter\Path, Operation\Get and Security\Requirement, has a before/after example in the Spec Attribute Reference. (#2301)
• The enums guide has a section on an enum as a type. (#2302)

What's Changed

• docs: drop the stale renderConfigSection() note from the toolchain page by @DerManoMann in #2300
• docs(Spec): add a usage example to every spec attribute subclass by @DerManoMann in #2301
• fix(Augmenter): an enum used as a type gets a schema of its own by @DerManoMann in #2302
• fix(Type): a class that is no component is not a nested schema's type by @DerManoMann in #2303
• fix(Type): a union with a class that is no component is left untyped by @DerManoMann in #2304
• fix(Console): allow symfony/console 5.4 by @DerManoMann in #2306
• fix(Compiler): order the top-level keys as classic does by @DerManoMann in #2309
• fix(Spec): a member's orphan attribute does not nest into a sibling's operation by @DerManoMann in #2308
• fix(Type): an open end of an int range is no bound by @DerManoMann in #2307

Full Changelog: 6.18.0...6.19.0