zircote/swagger-php 6.18.0

on PHP Packagist

Spec freeze

The spec attribute API is frozen. Existing attributes keep their shape from here on, and new fields and attributes may still be added. Builder is the stable entry point for every mode, and builds one document per instance. (#2299)

Spec and hybrid mode stay beta until v7, since the documents they generate may still change until spec becomes the default.

Spec pipeline

Required properties and defaults from PHP

Spec mode fills an object schema's required list and its properties' default from the PHP declarations. (#2296)

#[OA\Schema]
class Pet
{
    public function __construct(
        public int $id,
        public ?string $tag,
        public Status $status = Status::Available,
        public int $limit = 20,
    ) {}
}

Here id is required, status defaults to the case's value and limit to 20.

A property is required when its PHP type is not nullable and it has no default. Its PHP default becomes the schema default where the document can hold it: scalars, enum cases and arrays of them. null is skipped, and so is a value the schema's type does not allow. An explicit required or default on the attribute is kept as written. Classic annotations are not affected, in classic or in hybrid mode.

Smaller changes

• {method} in an explicit operationId is expanded by a new Augmenter\OperationIdTemplates. Before, Augmenter\OperationIds did that, so a pipeline removing it to stop generated ids also kept the templates as written, and the ids of split operations collided. (#2290)
• An invokable controller with methods: on its class gives the attributes on __invoke's parameters to every split operation, as a method does. Before, they were reported as ambiguous and the class was left out. (#2291)
• A member that fails to assemble is left out with a warning, and the rest of its class is kept. Before, the whole class went, and an inherited method under a path item failed the build. Without a logger the error is still thrown. (#2292)
• A $ref is checked in every document. A pointer to a component that does not exist is reported, and a bare name that matches a component gets a warning with the pointer to use. (#2288)
• A property or parameter typed with a class that has no schema, a value object for example, gets a warning naming the class and the member. (#2295)
• Hybrid mode reports annotations nothing can hold, and a second one where only one is allowed, in classic's words. Before, they were dropped without a warning. (#2287)

All modes

• Docblock type keywords are read in any case, so @var String and @var ?Int keep their type. A docblock type that still cannot be read is reported. (#2289)
• A class implementing DateTimeInterface, such as a DateTimeImmutable subclass, is a string with format date-time. Before, it was an empty schema. (#2293)
• A Schema, Type or Format in properties: without a string key throws, instead of passing through as an unnamed entry. (#2286)

Output changes

Required properties and defaults

This changes spec output. Most object schemas gain a required list, and properties with a PHP default gain a default. Spec output now differs from classic for most documents, and the migration guide no longer promises an identical one. (#2296)

Parameters with a PHP default

This changes spec output. int $page = 1 was a required parameter, since its type is not nullable. A parameter with a PHP default is now not required, unless it is a path parameter. An explicit required: still wins, and classic parameters in hybrid mode keep classic's rule. (#2297)

An explicit type on a nullable PHP type

This changes spec and hybrid output. An explicit type, oneOf, allOf or anyOf on the attribute is the whole type, and the PHP type's null is no longer added. type: 'object' on a ?array property stays object. null written on the attribute is kept. Hybrid now matches classic here. (#2298)

Documentation

• The guide and the Generator reference point at Builder for every mode, with withGenerator() for configuring classic's engine. The schema-query-parameter example uses Builder, and runs again. (#2299)

What's Changed

• chore(Types): raise phpstan to level 7 outside classic and the examples by @DerManoMann in #2286
• fix(Augmenter): check a $ref that points nowhere, with or without a class map by @DerManoMann in #2288
• fix(HybridBridge): report misplaced classic annotations as classic does by @DerManoMann in #2287
• fix(Type): read docblock keywords in any case, and report a type it cannot read by @DerManoMann in #2289
• fix(Augmenter): expand operationId templates in an augmenter of their own by @DerManoMann in #2290
• fix(Assembler): fan out __invoke's parameters for a methods: operation on its class by @DerManoMann in #2291
• fix(Assembler): leave out a member that fails assembly, not its class by @DerManoMann in #2292
• chore(deps-dev): bump @redocly/cli from 2.62.1 to 2.64.1 in the npm group across 1 directory by @dependabot[bot] in #2294
• fix(Type): map a DateTimeInterface subclass to date-time by @DerManoMann in #2293
• fix(Augmenter): warn when a class type has no schema by @DerManoMann in #2295
• feat(Augmenter): infer required and default from PHP declarations by @DerManoMann in #2296
• fix(Augmenter): a parameter with a PHP default is not required by @DerManoMann in #2297
• fix(Augmenter): an explicit type drops the PHP type's null by @DerManoMann in #2298
• docs: declare the attribute API frozen and Builder the stable entry point by @DerManoMann in #2299

Full Changelog: 6.17.1...6.18.0