zircote/swagger-php 6.14.0

on PHP Packagist

Shorter schemas in spec attributes

Inline properties in spec mode no longer need a Property wrapper each. properties can be keyed by name, with a Schema, a Type or a Format as the value. type takes the new OA\Type enum, and format the new OA\Format enum, which also implies the type in keyed properties. Any other format can still be passed as a string, and a list of Property works as before.

// Before
properties: [
    new OA\Property(property: 'id', schema: new OA\Schema(type: 'string', format: 'uuid')),
    new OA\Property(property: 'name', schema: new OA\Schema(type: 'string')),
    new OA\Property(property: 'createdAt', schema: new OA\Schema(type: 'string', format: 'date-time')),
]

// After
properties: [
    'id' => OA\Format::Uuid,
    'name' => OA\Type::String,
    'createdAt' => OA\Format::DateTime,
]

Both forms are converted in the constructor, so the generated document is the same. See Shortcuts.

Output changes

Classic keeps an explicit minimum, maximum or enum

This changes classic output. Type inference replaced values written in the attribute. Hybrid and spec already kept them, so classic now matches.

/** @var int<1, 10> */
#[OAT\Property(minimum: 5)]
public int $count;

#[OAT\Property(enum: ['cat', 'dog'])]
public Pet $kind;   // Pet is a schema component

# before
count: { type: integer, minimum: 1, maximum: 10 }
kind: { $ref: '#/components/schemas/Pet' }
# after
count: { type: integer, minimum: 5, maximum: 10 }
kind: { enum: [cat, dog] }

An explicit type: Pet::class still becomes a $ref. Also, type: 'long' now gives format: int64 rather than format: long, which is not a format in either specification.

3.0 writes nullable only beside a type

This changes 3.0 output in every mode. OpenAPI 3.0 only honours nullable: true next to a type, and both pipelines wrote it without one. A nullable reference now gets a branch that matches only null:

# before
owner:
  oneOf:
    - $ref: '#/components/schemas/Owner'
  nullable: true
# after
owner:
  oneOf:
    - $ref: '#/components/schemas/Owner'
    - { type: object, nullable: true, enum: [null] }

A nullable oneOf or anyOf with no type gets the same branch. A nullable value with nothing to type it, such as mixed, loses nullable, as in its 3.1 output. 3.1 and 3.2 output is unchanged.

Spec and hybrid YAML quotes response codes

Response codes in spec and hybrid YAML were written unquoted, so a YAML reader got an integer key. OpenAPI requires them quoted. They now come out as '200':, as in classic. JSON output is unchanged.

3.0 byte and binary in spec and hybrid

3.1 has no byte and binary formats. It writes them as contentEncoding: base64 and as a contentMediaType on a schema without type. When compiling to 3.0, spec and hybrid dropped both keywords without a warning. They now write format: byte and format: binary, and warn where there is no 3.0 form, for example a string holding JSON. Classic's 3.0 output is unchanged.

Documentation

Augmentation has a new table of which source sets a schema's type when the attribute, the docblock and the type-hint disagree, and the cases where classic differs.

Changes

• docs(Merge): stop calling merged attributes halves by @DerManoMann in #2246
• feat(Spec): accept properties keyed by name, and a Type enum for type by @DerManoMann in #2247
• feat(Spec): a Format enum, and 3.0 formats for contentEncoding and contentMediaType by @DerManoMann in #2248
• docs(Types): document which type source wins, and the one-version rule by @DerManoMann in #2249
• fix(Type): keep an explicit minimum, maximum or enum in classic type inference by @DerManoMann in #2250
• fix(Schema): 3.0 output keeps nullable only beside a type by @DerManoMann in #2251
• chore(deps-dev): bump the pinned dev tools, and let dependabot watch them by @DerManoMann in #2252
• chore(deps-dev): bump @redocly/cli from 2.57.0 to 2.62.1 in the npm group across 1 directory by @dependabot[bot] in #2253
• fix(Builder): quote response codes in hybrid and spec YAML by @DerManoMann in #2254

Full Changelog: 6.13.0...6.14.0