zircote/swagger-php 6.9.0

on PHP Packagist

Classic can now express the parts of OpenAPI 3.1 it always claimed to model: the full Header Object, a parameter's content, mutualTLS, the Info Object's summary, and the ten JSON Schema keywords 3.1 added.

src/Annotations and src/Attributes are closed to new capabilities, but an OpenAPI construct classic claims to model and cannot express is a defect rather than a missing feature, and v6 is the last major where classic is the primary API. A field-by-field diff of every classic annotation against the 3.1 object tables found eight such gaps; this release closes seven of them.

Upgrading from 6.8.x

3.0 documents lose two keywords they should never have carried. contentMediaType and contentEncoding were emitted into 3.0 output, where neither keyword exists — the 3.0 branch of @OA\Schema stripped only examples and const. They are dropped now, together with the other 3.1-only keywords:

 Attachment:
   type: string
-  contentMediaType: image/png
-  contentEncoding: base64

Nothing changes for 3.1 and 3.2.

The spec pipeline emits trait members in use order. Each trait used to be prepended separately, so two traits came out in reverse order and three reversed completely — declaring T1, T2, T3 emitted p3, p2, p1. Classic and hybrid were always right. Key order carries no meaning in OpenAPI, so no document was invalid, but regenerated files will diff.

Three classes moved, all spec-pipeline internals:

TypeMapper keeps a deprecated subclass at the old name, since a custom type resolver reaches it through AbstractTypeResolver. The other two have no shim.

Classic: the 3.1 object set

• The Header Object is complete. @OA\Header and #[OA\Header] gain style, explode, example, examples and content, so a header can finally carry an example or a media type instead of a bare schema. schema and content are mutually exclusive and saying both now warns.

• A parameter's content accepts a plain @OA\MediaType. The @OA\JsonContent / @OA\XmlContent shortcuts already worked; the verbose form was dropped silently, so a parameter written that way produced no content at all.

• mutualTLS is a valid @OA\SecurityScheme type. The enum rejected it outright. In 3.0 documents, where the type does not exist, the scheme warns and is omitted.

• @OA\Info gains summary. Dropped silently from 3.0 output, matching how License::$identifier is handled.

• Ten JSON Schema keywords arrive on every schema annotation — @OA\Schema, @OA\Property, @OA\Items, @OA\JsonContent, @OA\XmlContent and @OA\AdditionalProperties:

  if, then, else, prefixItems, dependentRequired, dependentSchemas, minContains, maxContains, unevaluatedItems, contentSchema

  Classic had adopted the 3.1 keywords partway — contains without minContains, unevaluatedProperties without unevaluatedItems — so the families were half-expressible. contentSchema was missing from the spec pipeline too and is added there as well.

  #[OA\Schema(
      type: 'array',
      prefixItems: [new OA\Schema(type: 'string'), new OA\Schema(type: 'integer')],
      contains: new OA\Schema(type: 'string'),
      minContains: 1,
  )]

  A 3.1 array schema described by prefixItems or contains no longer demands items; 3.0 still warns, since the keywords do not survive there.

Fixed

• A schema whose allOf named its parent by class-string emitted the same $ref twice in the spec and hybrid pipelines — dedup compared the raw values, and ran before class-strings resolved (#2185)
• Hybrid unwraps @OA\JsonContent / @OA\XmlContent through the bridge rather than by running two classic processors over a mapping it already knows (#2184)

New diagnostics

Generating 3.0 now warns for prefixItems, unevaluatedProperties, unevaluatedItems and if/then/else, with the same message text the spec compiler uses. contains, minContains, maxContains, patternProperties, propertyNames, dependentRequired, dependentSchemas, contentSchema, contentMediaType and contentEncoding drop silently.

A root @OA\Response whose component key looks like a status code (response: "404") is almost always a response meant for an operation, and now says so.

Documentation

Every reference page is generated through one set of section classes, so the annotation, attribute and spec-attribute pages stay in the same shape. CONTRIBUTING.md states the commit subject format and what a Changes entry is for.

What's Changed

• docs(Contributing): state the commit subject format and the allowed types by @DerManoMann in #2181
• fix(Augmenter): report a response component named after a status code by @DerManoMann in #2182
• fix(Tests): prefer spec expectations for hybrid in ExamplesTest and DocSnippetsTest by @DerManoMann in #2183
• refactor(HybridBridge): unwrap JsonContent/XmlContent without classic processors by @DerManoMann in #2184
• docs(Contributing): set the altitude for a Changes entry by @DerManoMann in #2188
• refactor(Docs): render every reference page through the section classes by @DerManoMann in #2187
• fix(Augmenter): deduplicate allOf refs after resolving class-strings by @DerManoMann in #2185
• refactor(Utils): move three classes to the subsystem that owns them by @DerManoMann in #2189
• fix(Augmenter): keep merged member order when expanding traits by @DerManoMann in #2186
• docs(Agents): carve spec-compliance defects out of the classic freeze by @DerManoMann in #2190
• fix(Annotations): model the full Header Object by @DerManoMann in #2191
• fix(Annotations): accept mutualTLS as a SecurityScheme type by @DerManoMann in #2193
• fix(Annotations): add the Info Object's summary field by @DerManoMann in #2194
• fix(Annotations): merge a plain MediaType into Parameter content by @DerManoMann in #2192
• fix(Annotations): model the JSON Schema keywords 3.1 added by @DerManoMann in #2195

Full Changelog: 6.8.1...6.9.0