zircote/swagger-php 6.16.0

on PHP Packagist

Spec pipeline

A Tag on a method or class tags its operations

#[OA\Tag] can now go on a method as well as a class. On a method it also tags that method's operations, and on a class every operation of the class. A class with no operations, such as one holding only Info, still only declares the tag. (#2274)

#[OA\Tag(name: 'users', description: 'Everything about users')]
class UserController
{
    #[OA\Tag(name: 'admin')]
    #[OA\Operation\Delete(path: '/users/{id}')]
    public function delete(int $id) {}
}

DELETE /users/{id} is tagged admin and users. The same tag declared in several places now folds into one, so a name-only tag no longer replaces a description declared elsewhere. Only a field set differently is reported.

The logger is the one channel

Result::log(), warnings() and errors() are deprecated and removed in 8.0. In spec and hybrid mode they never held the whole build log: a class skipped during the scan was reported to the logger only. The logger set with Builder::setLogger() receives every message. isValid() is unchanged. (#2266)

Smaller fixes

• new OA\Operation() without a method no longer throws. An operation that reaches the compiler still without one is left out of the document, now with a warning. (#2271)
• In hybrid mode, a ReflectionClass source is read for classic attributes too. Before, only the spec half saw it. A method or property reflector passed as a source is reported rather than dropped. (#2272)
• A class whose source file cannot be read, such as one defined through eval(), is read through reflection in spec, and skipped with a warning by the classic analyser. Before, a hybrid build failed. (#2273)

Rector set

• The classic-to-spec set adds #[OA\Components] to a class whose members declare keyed components (#2263).
• A method-level classic Tag migrated by the set is now a valid attribute. Before, the class was skipped. (#2274)

Output changes

A tag on a class with operations

This changes spec output. A Tag on a class that also declares operations now tags those operations. Move the tag to a class without operations to keep it a declaration only. (#2274)

A component on a member needs #[OA\Components]

This changes spec output. A keyed component declared on a method or property is a component only when its class carries #[OA\Components]. Before, one on a method was kept and one on a property was lost without a warning. Outside a holder it is now left out with a warning that says to add the wrapper. A schema on a property of a #[OA\Components] class becomes a component named after the property. (#2263)

Nullable compositions in 3.1 and 3.2

This changes hybrid and spec output. A schema with nullable: true, no type and a oneOf or anyOf lost the null in 3.1 and 3.2. It now gets a {type: null} branch, as in 3.0 and classic. (#2267)

summary and description beside a $ref

This changes hybrid and spec output. 3.1 and 3.2 now keep summary and description on a Reference Object, as classic does. 3.0 does not allow them, so they are still dropped there, now with a warning. A security scheme that is a $ref compiles to a reference instead of an empty object. (#2268)

No type: object inferred from allOf

This changes hybrid and spec output. An untyped schema with an allOf got type: object, which made a composition of non-objects unsatisfiable. The type is now left off, as in classic. (#2269)

Operation methods per version

This changes hybrid and spec output. An operation is written only under a method its version defines. A query operation is left out of 3.0 and 3.1 with a warning, as classic leaves it out. 3.2 keeps a QUERY request body, which it dropped before. (#2270)

Hybrid keeps schema components declared on properties

This changes hybrid output. A named classic Schema on a property is a component, as in classic. Hybrid left it out, and every $ref to it pointed at nothing. (#2264)

Hybrid keeps a repeated tag's description

This changes hybrid output. A classic tag declared with a description and again by name only keeps the description. Classic keeps the last declaration whole. (#2274)

Classic

A serialized Context leaves out the non-OpenApi attributes found next to an annotation. One holding a closure, such as Symfony's #[IsGranted] on PHP 8.5, made serialize() fail, so a cached OpenApi could not be written. After unserialize() those attributes are gone. (#2265, nelmio/NelmioApiDocBundle#2817)

What's Changed

• fix(Spec): require #[Components] for a component declared on a member by @DerManoMann in #2263
• fix(HybridBridge): keep schema components declared on properties by @DerManoMann in #2264
• fix(Context): leave foreign attributes out of a serialized context by @DerManoMann in #2265
• feat(Builder): deprecate the log accessors on Result by @DerManoMann in #2266
• fix(Compiler): keep summary and description beside a $ref in 3.1 and 3.2 by @DerManoMann in #2268
• fix(Augmenter): stop inferring type object from allOf by @DerManoMann in #2269
• fix(Compiler): emit only the operation methods each version defines by @DerManoMann in #2270
• fix(Builder): read classic attributes from reflector sources in hybrid by @DerManoMann in #2272
• fix(Compiler): keep a nullable oneOf or anyOf nullable in 3.1 and 3.2 by @DerManoMann in #2267
• fix(Spec): accept an operation without a method by @DerManoMann in #2271
• fix(Utils): handle a class whose source file cannot be read by @DerManoMann in #2273
• feat(Spec): apply a Tag on a method or class to its operations by @DerManoMann in #2274

Full Changelog: 6.15.0...6.16.0