NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist, #346 most downloaded on Packagist
Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations
Latest stable
7.8.0
Last release 4 days ago
18 Nov 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 57 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
241 releases · first in 2012
Drag across the ruler to compare, or tap a release to open it.
…, a discriminator's defaultMapping , and deprecated and oauth2MetadataUrl on a security scheme
7.8 brings all the OpenAPI 3.2 support to the spec attributes. A 3.2 document can use every field and value the version adds. 3.0 and 3.1 write a field in its older form where there is one, and leave it out with a warning where there is not.
self on the document, a server name, a response summary, an example's dataValue and serializedValue, a discriminator's defaultMapping, and deprecated and oauth2MetadataUrl on a security scheme (#2149)cookie parameter style (#2408)itemSchema on a media type, and encodings by position with prefixEncoding and itemEncoding (#2412)querystring parameter location, with OA\Parameter\Querystring (#2414)OA\Operation\Query for the query method (#2416)additionalOperations (#2417)nodeType, written as attribute or wrapped before 3.2 where they say the same (#2418). A schema can take the node type alone, as xml: OA\XmlNodeType::Cdata (#2419)summary. Before, it was left out with a warning (#2149)COPY to additionalOperations. Before, it was left out with a warning (#2417)style: cookie with a warning. Before, it was written, and the document was invalid (#2408)Full Changelog: 7.7.0...7.8.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
7.7 reports every property an OpenAPI version leaves out, where most were dropped without a word before, and writes the extensions on components and p
7.7 reports every property an OpenAPI version leaves out, where most were dropped without a word before, and writes the extensions on components and properties that were lost.
Both change the log or the generated document. Changed output in 7.7 has the details.
summary, parent and kind, and at 3.0 an info summary and eight 2020-12 schema keywords. Before, they were left out without a message. The license identifier and media type component warnings now read like the others (#2396, #2404)x on #[OA\Components] is written on components, and x on a property on its schema. Before, both were left out without a warning (#2405)UNSUPPORTED_PROPERTIES, and filter() drops it. The 3.0 compiler's own compileInfo() and compileLicense() and the 3.2 compiler's own compileTag() are gone (#2403, docs)TypeResolver reads a member's types and maps them in two steps, so a subclass can change the types in between through toSchemaType() (#2398)x on Security\Requirement, removed in 8.0. A Security Requirement Object cannot carry extensions, so it is left out with a warning (#2405)filter() by @DerManoMann in #2403Full Changelog: 7.6.0...7.7.0
chore(Utils): deprecate TokenScanner by @DerManoMann in #2388
7.6 adds a parser for OpenAPI 3.1 documents. With it, Builder::withDocument() adds a hand-written document to what the attributes describe, for example webhooks with no PHP code behind them. Plugins can now also be found through the packages installed, and a spec build no longer parses PHP files.
Two changes affect the generated document or the log. Changed output in 7.6 has the details.
use now adds its properties. Before, they were missing, with a warning. Thanks @vencakrecl (#2392)OpenApi\Parser reads an OpenAPI 3.1 document into a Specification, and Builder::withDocument() adds one to a spec or hybrid build. Where both describe the same thing, the attributes win. Only 3.1 documents are supported (#2387, docs, cookbook)Builder::withDiscoveredPlugins() adds the plugins installed packages declare in their Composer metadata. It is opt-in (#2385, docs)Parameter, RequestBody, Response, Header, Link and Security\Scheme take a summary, written beside a $ref from 3.1 on (#2389)AttributeFactory takes any SourceInspectorInterface. The default SourceInspector tells a class's own members by reflection, so a spec build parses no PHP. A subclass reading $tokenScanner gets the interface (#2373, #2374, docs)$summary on one of those six attributes needs it as public ?string $summary (#2389)TokenScanner, removed in 8.0. Use SourceInspector (#2388)composer.json no longer conflicts with symfony/process, which swagger-php does not depend on (#2395)validate() at 500 schemas went from 97 to 39 ms (#2367)TokenScanner by @DerManoMann in #2388Specification by @DerManoMann in #2387Full Changelog: 7.5.0...7.6.0
7.5 is about the messages spec and hybrid log. A problem that makes the document invalid, or loses something declared, is now an error, and every mess
7.5 is about the messages spec and hybrid log. A problem that makes the document invalid, or loses something declared, is now an error, and every message follows one form. The Rector set also keeps the operations it used to lose where classic copied an attribute into several others.
Both message changes affect builds and tests that read the log. Changed output in 7.5 has the details.
error, rather than a warning, where the document is invalid or something declared is lost. Such a build makes Result::isValid() false, and the CLI exits with 1. Classic type aliases and the array form of a security requirement log a notice (#2375)Ref: dangling reference '#/components/schemas/Pet' - no such component now reads Reference "#/components/schemas/Pet" points to no component. A test matching log lines in full needs updating. Classic's messages are unchanged (#2377)fan: Fan::All where classic copied an attribute into several others, such as one response beside both a Get and a Post. Spec used to skip such a method as an ambiguous merge. ->withSkip([FanOutRector::class]) turns it off (#2372, docs)Full Changelog: 7.4.0...7.5.0
7.4 is a fixes and performance release. Scanning no longer reads a class's source again for every property, which matters most on slow filesystems suc
7.4 is a fixes and performance release. Scanning no longer reads a class's source again for every property, which matters most on slow filesystems such as Docker Desktop bind mounts.
Two changes affect the generated document. Changed output in 7.4 has the details.
components. Where nothing else adds the class, a type that used it is left out, with a warning (#2361)@example is cast by the property's type, so @example 1 on an int writes 1 rather than '1'. #[OA\Examples(value:)] keeps false and floats as given (#2368)$ref, under 3.0 and 3.1 (#2362)Builder::createSpecification(), so a subclass can supply its own specification (#2366)Resolver::getTypedReflectors() is replaced by getPropertyTypes(). A subclass overriding it overrides getPropertyTypes() instead (#2361, docs)TypeContextFactory per TypeResolver, and TokenScanner::detailsFor() answered from the cache for a scanned file. Thanks @leo-pansonato (#2364, #2365)Full Changelog: 7.3.0...7.4.0
7.3 adds plugins: a library can ship its translators, resolvers and augmenters together with the wiring, and a project names the plugin rather than re
7.3 adds plugins: a library can ship its translators, resolvers and augmenters together with the wiring, and a project names the plugin rather than repeating that wiring. Plugins configure the spec pipeline and are not used in classic mode.
One change affects what a build reports. Changed output in 7.3 has the details.
Result::isValid(), log(), warnings() and errors() include what the source scan, the resolvers and skipped classes log. An error logged there now makes isValid() false, as it already made the CLI exit with an error (#2360)Contracts\PluginInterface configures the builder through Builder\Hooks: the resolver, augmenters, mergers, attribute factory and contributions. The component namer, type resolver, compiler and version stay with whoever runs the build. Builder::withPlugins() takes plugin classes, classes mapped to their settings, or instances, and runs them in the order given. An invalid entry is skipped and logged as an error. On the command line, --plugin adds a plugin built without settings (#2360, docs)new Builder($logger) takes the PSR-3 logger. A plugin implementing LoggerAwareInterface gets it (#2360)Builder::$logger holds, and Builder::getLogger() returns, a CollectingLogger that forwards to the logger the builder is given. A subclass assigning its own logger to $logger wraps it first, new CollectingLogger($logger). A subclass overriding getLogger() declares CollectingLogger as its return type (#2360, docs)Builder::setLogger(). Pass the logger to the constructor. What plugins log in withPlugins() before setLogger() is called does not reach the logger (#2360)Full Changelog: 7.2.0...7.3.0
A component schema backed by a method no longer takes the method's description and deprecated
7.2 is about describing a class more than once, which 7.1 started. Each description now gets a name of its own, and a resolver can make one when a reference asks for it. Everything below applies to spec and hybrid mode. Classic mode is unchanged.
Two changes affect the generated document. Changed output in 7.2 has the details.
Author-groups.summary rather than Author. It used to take its class's name and clash with the plain component, so the document kept only one of them. Components without qualifiers keep their names (#2345)deprecated (#2335)KeyResolverInterface is asked about a class plus its qualifiers, so a Schema\Ref with qualifiers no component has can have its description made on demand. KeyResolverTrait answers resolve() with resolveKey(). Resolvers that only know class names keep working, and are asked about references without qualifiers only (#2346, docs)ComponentNamerAwareInterface, AttributeFactoryAwareInterface or TypeResolverAwareInterface. One type resolver is shared by everything reading PHP types (#2353, #2354)Builder::setTypeResolver(). A type resolver set on Types with setTypeResolver() is now replaced when the build runs. Set it on the builder instead (#2357)Walker::visit() takes a list of classes and visits each matching attribute once, and Walker::eachTypedAttribute() visits the properties, parameters and request bodies that Types types (#2355, #2358)T&\Countable with an unbounded T, is logged as unsupported rather than ending the build (#2352){}, as OpenAPI requires. Also in 6.20.2 (#2348)Spec\Header::$description defaults to Undefined::UNDEFINED, so an omitted description can be inferred and an explicit null suppresses it. Code checking the default with === null should use Undefined::isDefault() (#2335)ResolverInterface. Implement KeyResolverInterface, which extends it; a class name is the key without qualifiers. A resolver implementing ResolverInterface alone triggers a runtime deprecation naming its class (#2347)Full Changelog: 7.1.0...7.2.0
7.1 is about components: how they are named, how a class is matched to them, and which ones Cleanup keeps. Everything below applies to spec and hybrid
7.1 is about components: how they are named, how a class is matched to them, and which ones Cleanup keeps. Everything below applies to spec and hybrid mode. Classic mode is unchanged.
Two changes affect the generated document. Changed output in 7.1 has the details.
required: true, as OpenAPI requires. A path parameter set to anything else logs a warning (#2338)$ref given as the class, or a property typed with it, resolves to none of them and logs a warning. A property typed with a class that has a schema references the schema, not a component in another bucket (#2342)Builder::setComponentNamer() and --component-namer choose how components without an explicit name are named. ShortName is the default, QualifiedName uses the whole class name, so two classes that share a short name no longer claim one name, and a custom namer implements ComponentNamerInterface (#2341, docs)Schema\Ref with the same qualifiers references it. In an augmenter, ComponentIndex::findByKey() and findAllByKey() look components up by key (#2342, docs)Cleanup keeps a component whose meta value under Cleanup::class is false, referenced or not. The meta key is configurable as cleanup.metaKey (#2339)RefInterface. Every spec attribute with a ref implements Contracts\RefInterface, with getRefValue(), getRefKey() and setRef() (#2343)The fixes from 6.20.1 are in 7.1 as well: #2328, #2330, #2331, #2333 and #2334.
ComponentIndex::buildRefMap(). Use ComponentIndex::findByKey(), which takes the bucket a use meansOpenApi31Compiler::refString(). Use RefInterface::getRefValue() on the attribute that holds the refFull Changelog: https://github.com/zircote/swagger-php/compare/7.0.0...7.1.0
Classic attributes and docblock annotations still work, in hybrid and in classic mode. They are deprecated and removed in 8.0.
Hybrid is now the default mode, and spec attributes are stable. Classic attributes and docblock annotations still work, in hybrid and in classic mode. They are deprecated and removed in 8.0.
Builder is now the entry point for generating a document. In 6.x it was available next to Generator. With Generator deprecated, code that calls it directly moves to Builder.
For most installations upgrading does not require any code changes. Migrating to v7 covers the details.
Without a mode set, the document is built in hybrid mode. Hybrid scans the same classic attributes and docblock annotations as classic, so for most projects the document stays the same. The known differences:
Builder::setVersion('3.0.0') or --version 3.0.0 keeps 3.0.0cleanup.enabled set to false keeps themproperties declared beside allOf on a nested property stay beside it-c takes augmenter keys rather than processor keys, apart from generator.*Custom processors only see the annotation instances as scanned in hybrid mode. A project that depends on them can stay on classic with Builder::setMode(Mode::CLASSIC) or --mode classic while the processors are rewritten as augmenters.
nikic/php-parser ^5.0^5.4 || ^6.4 || ^7.0 || ^8.0The elements deprecated for 7.0:
LegacyTypeResolverTokenScanner, Pipeline, SourceFinder and TypeMapperTypeResolverInterface::NATIVE_TYPE_MAPGenerator, Analysis and the analysers. Augmenters and Builder replace themBuilder::setMode(), Mode and the CLI's --modeSecurityToRequirementRector rewrites themIn 8.0 spec attributes move from OpenApi\Spec to OpenApi\Attributes. For code already written against OpenApi\Spec, that is one use line per file.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.20.0...7.0.0
A trait or interface imported through a grouped use , for example something like use Vendor\Model\{HasFields, Contract}; , resolves now. Before, the t
use, for example something like use Vendor\Model\{HasFields, Contract};, resolves now. Before, the trait's properties were missing from the schema, with an Unexpected @OA\Property() warning (#2392 by @vencakrecl, reported in #2391)Backported from master in #2394.
Full Changelog: 6.20.3...6.20.4
fix(Backport): three fixes from master for 6.20.3 by @DerManoMann in #2376
Full Changelog: 6.20.2...6.20.3
An empty media type compiles to {} , not [] , and so does a security requirement naming no scheme. Before, validators rejected the document ( #2348 ,
{}, not [], and so does a security requirement naming no scheme. Before, validators rejected the document (#2348, reported in #2344)Backported from master in #2351.
Full Changelog: 6.20.1...6.20.2
An inferred empty default on an object schema is written as {}, not [] (#2328, reported in #2327)
{}, not [] (#2328, reported in #2327)@example takes the schema's type. @example 42 on an integer property now gives 42, not "42" (#2330)$schema->schema = 'Pet', is read. Before, the schema was left out of components without a warning (#2333)#[OA\ExternalDocumentation] next to tags that already have their own goes to the root. Before, classic dropped it silently and hybrid warned about it twice (#2334)Backported from master in #2337.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.20.0...6.20.1
symfony/console below 5.4.35, symfony/finder below 5.3.7 and symfony/string below 5.4.41 conflict. Those releases print PHP deprecations into the outp…
The classic-to-spec set migrates more classic arguments that spec does not take. Before, each of these stayed in place and the migrated attribute threw Unknown named parameter once it loaded.
Encoding's property: is renamed to encoding:, and a Property with encoding: becomes Property\Encoded, keeping its schema keywords (#2317)spaceDelimited:, pipeDelimited: and deepObject: are rewritten to style:. Classic writes them into the document as keys OpenAPI does not define, so the migrated document gains the style and loses the stray key (#2319)in: is dropped where it matches the parameter class, and allowEmptyValue:, allowReserved: and styles are dropped where OpenAPI does not define them (#2320)ComponentsHolderRector no longer makes a class a components holder for a Response keyed by a status code (#2318)The arguments the set leaves for the author are listed in Migrating to spec.
#[OA\Examples] and #[OA\Webhook]. Before, both were dropped with a warning, and a $ref to such an example was left dangling (#2313)allOf and an empty properties: [] gets no extra allOf entry holding only type: object, as in classic (#2314)symfony/console below 5.4.35, symfony/finder below 5.3.7 and symfony/string below 5.4.41 conflict. Those releases print PHP deprecations into the output of bin/openapi wherever display_errors is on, which breaks its YAML and JSON (#2310)@template is recognised in docblock types, so list<T> no longer logs "Unsupported docblock type". The document was not affected (#2316, reported in #2315)Full Changelog: https://github.com/zircote/swagger-php/compare/6.19.0...6.20.0
symfony/console accepts ^5.4, next to ^6.4, ^7.0 and ^8.0. Symfony 5.4 gets security fixes until February 2029.
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.
symfony/console accepts ^5.4, next to ^6.4, ^7.0 and ^8.0. Symfony 5.4 gets security fixes until February 2029. (#2306)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)
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)
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)
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)
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)
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)
OpenApi\Spec, such as Parameter\Path, Operation\Get and Security\Requirement, has a before/after example in the Spec Attribute Reference. (#2301)Full Changelog: https://github.com/zircote/swagger-php/compare/6.18.0...6.19.0
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
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 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.
{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)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)$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)@var String and @var ?Int keep their type. A docblock type that still cannot be read is reported. (#2289)DateTimeInterface, such as a DateTimeImmutable subclass, is a string with format date-time. Before, it was an empty schema. (#2293)Schema, Type or Format in properties: without a string key throws, instead of passing through as an unnamed entry. (#2286)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)
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)
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)
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)Full Changelog: https://github.com/zircote/swagger-php/compare/6.17.1...6.18.0
unevaluatedProperties takes false as well as a schema, on Schema, Property, Items, AdditionalProperties, JsonContent and XmlContent. Before, false was
unevaluatedProperties takes false as well as a schema, on Schema, Property, Items, AdditionalProperties, JsonContent and XmlContent. Before, false was a TypeError. It is written to 3.1 and 3.2, and left out of 3.0 with a warning. (#2275)
Full Changelog: https://github.com/zircote/swagger-php/compare/6.17.0...6.17.1
Every spec attribute takes fan:. With fan: OA\Fan::All, an attribute that more than one attribute could hold goes into each of them, as a copy. Withou
Every spec attribute takes fan:. With fan: OA\Fan::All, an attribute that more than one attribute could hold goes into each of them, as a copy. Without it, that is an error naming the candidates. (#2276)
#[OA\Operation\Put(path: '/pets/{id}')]
#[OA\Operation\Delete(path: '/pets/{id}')]
#[OA\Response(response: 404, description: 'Not found', fan: OA\Fan::All)]
public function change(
#[OA\Parameter\Path(name: 'id', fan: OA\Fan::All)]
int $id,
) {}
Both operations get the 404 response and the id parameter. The same works for a Header next to several responses. The targets have to be of one type: a MediaType next to both a Response and a RequestBody stays an error.
OA\Operation takes methods:, and is split into one operation per method during assembly. While it is the only operation on its method, everything that nests into it goes to each method without a fan. (#2280)
#[OA\Operation(path: '/pets/{id}', operationId: '{method}Pet', methods: [OA\HttpMethod::Put, OA\HttpMethod::Patch])]
#[OA\Response(response: 204, description: 'Updated')]
public function update(
#[OA\Parameter\Path(name: 'id')]
int $id,
) {}
{method} in an explicit operationId is replaced by each operation's method, here putPet and patchPet. An operationId without it is dropped on several methods, with a warning, and each operation gets a generated one. method and methods together are an error.
The split is the new default translator Assembler\OperationMethodsTranslator. A custom translator that creates methods: operations has to run before it, so insert() it ahead of that class rather than add() it.
content: on Response and RequestBody takes a bare schema, the payload of one media type. nelmio's content: new Model(...) has worked this way for years. (#2285)
#[OA\Response(response: 200, description: 'The pet', content: new OA\Schema\Ref(Pet::class))]
The new DefaultMediaType augmenter gives every media type without a type application/json, or whatever defaultMediaType.mediaType is set to. An explicit type is never changed, so a single response can still name its own. Parameter and Header keep content: as media types, since their own schema: means something else.
LoggerAwareInterface is given the logger set with Builder::setLogger(). So is a translator. (#2281, #2280)PathItem pushes into its operations, and a PathItem repeated per path, each get their own copy. Before, they shared children, so an augmenter changing one changed them all. No built-in augmenter does that, so the default output is the same. (#2278)ComponentsHolderRector takes ROUTE_ATTRIBUTES, a list of route attribute classes, empty by default. A method carrying one does not make its class a holder, so a #[Response] decorating a framework route is left as it is. The migration guide shows the set configured with Symfony's Route from a project's own rector.php. (#2282)This changes spec output. An attribute on a PHP parameter that matched more than one operation went into the first one, without a warning. It is now an error, and the class is left out with a warning, like an ambiguous sibling already was. Add fan: OA\Fan::All to put it into each, or nest it where it belongs. (#2276)
Schema\Items wherever it is nestedThis changes spec output. A Schema\Items was only expanded into an array schema as the schema of a media type, parameter, header or property. Inside oneOf, anyOf, allOf, not, prefixItems or additionalProperties, or as a class-level component, it compiled as its item schema. It is now an array everywhere, except directly in the items of a plain schema, where it stays the item schema, as the rector set writes it. A class-level Schema\Items keeps its component. (#2279)
{method} in an explicit operationIdThis changes spec output. {method} in an explicit operationId is now replaced by the operation's method, on every operation. An id that contained it literally changes. (#2280)
This changes spec output for a Specification compiled without the DefaultMediaType augmenter, such as a custom pipeline. A media type without a type was compiled as application/json; it is now left out with a warning. The default pipeline is not affected. A media type repeated in one content list now warns, and the last one is still kept. (#2285)
Merge\Mode cases. (#2284)api example shares a header through fan:, the guide's fan: and methods: examples run as tests, and the migration guide offers both for headers and responses shared by several targets. (#2283)Full Changelog: https://github.com/zircote/swagger-php/compare/6.16.0...6.17.0
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…
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.
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)
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)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)eval(), is read through reflection in spec, and skipped with a warning by the classic analyser. Before, a hybrid build failed. (#2273)#[OA\Components] to a class whose members declare keyed components (#2263).Tag migrated by the set is now a valid attribute. Before, the class was skipped. (#2274)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)
#[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)
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 $refThis 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)
type: object inferred from allOfThis 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)
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)
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)
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)
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)
Full Changelog: https://github.com/zircote/swagger-php/compare/6.15.0...6.16.0
…accept component:. Before, following the 6.12 deprecation on one of them failed with Unknown named parameter $component and the class was skipped.
#[OA\Components] holds components declared on its membersA class carrying #[OA\Components] now takes in the components declared on its methods. One without a key is named after the method, the way a class names its own. Many schemas can share one class, one method each, and each method's docblock becomes its description. A parameter is still keyed by its name:. (#2261)
#[OA\Components]
class Models
{
/** A thing someone owns. */
#[OA\Schema(type: OA\Type::Object, properties: ['id' => OA\Type::Integer])]
public function thing() {}
#[OA\Response(description: 'No such thing')]
public function notFound() {}
}
This gives #/components/schemas/thing and #/components/responses/notFound.
Parameter\Query, Path, Header, Cookie), MediaType\Json and Xml, and the typed security schemes accept component:. Before, following the 6.12 deprecation on one of them failed with Unknown named parameter $component and the class was skipped. (#2260)The classic-to-spec set now also:
type: 'long' for example, to the type and format they stand for (#2255)Property's schema:, a pointer or a ::class, into the nested schema's ref (#2258)security: to a Security\Requirement, bare scheme names and arrays alike (#2259, #2262)This changes hybrid output. Classic reads security: ['bearerAuth'] as that scheme with no scopes. Hybrid dropped the string without a word and wrote security: [], so the operation was documented as public. It now reads it as classic does, and warns, since spec does not accept the form. Spec used to crash on it with a TypeError. It now drops it with a warning, and the operation falls back to the requirements declared above it. (#2259)
This changes hybrid output. A named Schema on a method, #[OAT\Schema(schema: 'Thing', ...)] on a model() method for example, is a component in classic. Hybrid dropped it, and every $ref to it pointed at nothing. It is now kept as classic keeps it. (#2256)
This changes hybrid and spec output. Hybrid and spec wrote type: 'long', 'int', 'float', 'bool', 'date' and the other names classic maps as they were, which is not a valid type, with an "unknown type" warning. They now get the type and format classic gives them, integer with int64 for long for example, and a deprecation per alias in place of the warning. The translation is removed in 8.0, and -c typeAliases.enabled=false switches it off now. (#2255)
Full Changelog: https://github.com/zircote/swagger-php/compare/6.14.0...6.15.0
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
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.
minimum, maximum or enumThis 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.
nullable only beside a typeThis 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.
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.
byte and binary in spec and hybrid3.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.
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.
properties keyed by name, and a Type enum for type by @DerManoMann in https://github.com/zircote/swagger-php/pull/2247Format enum, and 3.0 formats for contentEncoding and contentMediaType by @DerManoMann in https://github.com/zircote/swagger-php/pull/2248nullable only beside a type by @DerManoMann in https://github.com/zircote/swagger-php/pull/2251Full Changelog: https://github.com/zircote/swagger-php/compare/6.13.0...6.14.0
Beside a plain $ref in 3.1, it kept only description. title, default, example, examples, deprecated, readOnly and writeOnly are now kept in every mode…
A new Rector set rewrites OpenApi\Attributes code to OpenApi\Spec. Pass it to Rector as --config vendor/zircote/swagger-php/rector/set/classic-to-spec.php. Renaming classes is not enough to migrate. Spec orders constructor parameters differently. Property, JsonContent and XmlContent no longer take schema keywords, which go in a nested schema: instead. So renamed code parses and then fails when the document is generated. The set first turns positional arguments into named ones, using the classic constructor's parameter names, and then renames the classes. It also lifts info:, servers:, tags: and externalDocs: off a root OpenApi into separate attributes, and moves schema keywords off Property, JsonContent and XmlContent into a nested schema:.
The set was run over two real codebases, one with 22 files of classic attributes and one with 354. Spec mode then generated the same document as classic for both. Migrating to spec attributes covers running it, the cases it leaves for you, and the code that drives the generator, which the set does not rewrite.
In spec and hybrid mode, Cleanup removes every component that no path references, and it is on by default. It used to do this silently, so a schema kept only for client code generation disappeared from the document with no reason given. A run that removes anything now prints one notice on stderr, with the count and the setting that keeps them, cleanup.enabled=false.
That setting did not work in hybrid. -c went to the classic Generator, whose processors hybrid does not run, so every key except generator.* was silently ignored. Hybrid now sends generator.* to the Generator and every other key to the augmenters, so -c cleanup.enabled=false works. A hybrid key that no augmenter knows, such as -c operationId.hash=false, now prints an "Unknown config key" warning. It had no effect before either. See Behavioral differences.
$ref schema keeps its keywordsA property typed with a schema class compiles to a $ref, and keywords written on it, such as title or example, were dropped. Spec and hybrid kept only description. Classic writes a nullable $ref as a oneOf and kept everything on that oneOf. Beside a plain $ref in 3.1, it kept only description. title, default, example, examples, deprecated, readOnly and writeOnly are now kept in every mode, on the oneOf around a nullable $ref and beside a plain $ref in 3.1.
This changes 3.1 output for existing sources. A title or example declared beside a $ref now appears. In 3.0, the first of examples is written as example on the oneOf around a nullable $ref.
security: [['bearerAuth']], a list of scheme names instead of the [['bearerAuth' => []]] map, stopped hybrid and spec with a TypeError. Classic wrote it out as given, which is not a valid requirement. All three modes now read a bare scheme name as that scheme with no scopes.
Classic also wrote the optional requirement in a root security: [[]] as [] instead of {}. Root-level security now writes each requirement as an object, as operation-level security already did, so it comes out as [{}].
$ref is inferred only to a componentWhen a property's PHP type is a class, spec and hybrid added a $ref to it even when the class had no #[Schema]. The document then carried a class name that resolves to nothing, such as $ref: Brick\Math\BigInteger. The same inference replaced an explicit enum on a property typed with a backed enum, so the case values were lost. A $ref is now inferred only to a class that is a component, and never where enum is set. Classic, hybrid and spec now give the same output for both.
Since 6.10, a class whose attributes fail to instantiate is skipped with a warning when the scan reaches it. Reached through a reference from another class, the same class ended the run with no document. Which way it was reached first depended on scan order. Both ways now skip the class with the same warning, and the run continues.
By default, the later of two operations on the same path and method replaces the earlier one whole. When a route table contributed through withSpecification() and an attribute both describe an operation, the attribute has to repeat everything the route gave. Merge\Operations folds the two instead. It takes what only one half sets, and folds parameters by name and location and responses by status code. Merge\Mode decides who wins where both set the same field. A field both halves set to different values is logged as a warning.
It is opt-in, so nothing changes until you register it with Builder::withMergers(), ahead of the default Merge\LastWins, which claims every type: $mergers->insert(new Merge\Operations(), Merge\LastWins::class). A new Parameters augmenter, on by default, gives a ref parameter its component's name and location before the merge runs. That way a ref parameter and an inline one for the same name and location fold into one, and the reference is what survives. See Mergers.
SpecificationSeveral things a package needed to copy from the augmenters are now public:
PathItemHierarchy::prefixFor() and pathFor() give the prefix an operation's #[PathItem] chain composes to, and the operation's full path. pathFor() reads the path as declared, so calling it after the PathItems augmenter has run adds the prefix twice.PathItemHierarchy::parametersFor() lists the parameters an operation inherits from that chain, keyed by name and location. The nearer path item wins.SourceLocation::qualifiedMethod() names the method a location is in as Class::method, using the class that declares it. Operation ids are built from it and come out unchanged.ComponentIndex::parameterKey() gives a parameter's key, its name and location, before the build has resolved it. A parameter that is only a ref takes both from its component.PathItems::resolvePrefix() is removed. It was protected, so a subclass that calls or overrides it has to move to prefixFor().
Every hand-written page under guide/ and dev/, and every ADR, has been rewritten in plain sentences, following the new Voice section of Writing documentation.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.12.0...6.13.0
…header:, link: and example: now trigger a deprecation, and are removed in 8.0. Only their use as a component key is deprecated: response: 404 on a nes…
Without -o, bin/openapi writes the document to stdout, and its warnings went there too, so openapi src > openapi.yaml put them into the file ahead of the YAML. Diagnostics now go to stderr, and stdout carries only the document.
A script that reads warnings from stdout has to read stderr instead. With -o, warnings used to be the only thing on stdout, so a check like openapi src -o openapi.yaml | grep -q warning && exit 1 worked. It now finds nothing and passes. Read both streams with 2>&1.
security: [] is keptAn operation opts out of a root security requirement with security: []. Spec and hybrid modes dropped the empty list as if it were unset, so the operation documented as requiring the root's authentication. It is now emitted. Classic mode was not affected.
component: key on every reusable attributeEach reusable OpenApi\Spec attribute names the key it is filed under with component:, in place of a field spelled after its own type. PathItem and MediaType take it too, and can now be reused: a keyed PathItem is a components.pathItems entry from 3.1, and a keyed MediaType a components.mediaTypes entry from 3.2. See Components.
The old spellings keep working and produce the same document. Used as a component key, schema:, parameter:, request:, securityScheme:, response:, header:, link: and example: now trigger a deprecation, and are removed in 8.0. Only their use as a component key is deprecated: response: 404 on a nested response is the nesting key and stays. Classic attributes report nothing.
A schema's title is no longer used as its component key; a schema with no key is reported.
Builder::withSpecification() hands the assembled Specification to a callable after the scan and before resolution. What it adds is resolved, augmented and compiled with the scanned sources, so a $ref in a contribution resolves. That makes it the place for metadata with nothing to scan: an entity registry, a serializer's configuration, another library's attributes. See Extension points.
Two operations on the same path and method, or two schemas with the same key, used to be settled by the compiler, which kept whichever it wrote last and said nothing. A merger pass now applies one rule to every root collection: the later entry wins, and the collision is reported with both locations. Builder::withMergers() takes your own mergers ahead of it, and getMeta()/setMeta() on every attribute lets a package mark its contributions so its merger can recognise them.
One output change: for two PathItems on the same path, the later one now wins, as everything else does. It used to be the first.
Result now also carries what the spec pipeline logged during the build, not only the compiler's diagnostics.
An attribute that matches more than one sibling on the same target, such as a Header stacked beside two Responses, now says what to do about it: nest it in the one it belongs to, or give it a component and reference it from each.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.11.0...6.12.0
Parsing a docblock annotation triggers a runtime deprecation, once per Generator run and only when an annotation is actually parsed — a project that h…
Parsing a docblock annotation triggers a runtime deprecation, once per Generator run and only
when an annotation is actually parsed — a project that has moved to attributes still has
docblocks everywhere and stays quiet.
Most people will see nothing. trigger_deprecation() is suppressed by design, so the notice
surfaces only where a deprecation handler is listening for one. It is a heads-up, not a change
of behaviour.
The README has recommended attributes over annotations since 4.8; the code now agrees. Docblock
support is marked @deprecated and removed in 8.0 — it keeps working unchanged through v7.
ROADMAP.md said classic code is marked in v6 and removed in v7, and the markers in src/ did
not say either. The rule is now written down — a marker names the version that removes the
thing, and nothing is removed before the version its marker names — and every marker in the
tree follows it.
Where that lands: anything classic depends on goes when classic does, including the sentinels
Generator::UNDEFINED and Generator::isDefault(), which classic processors and hand-built
annotation objects both use.
Specification::buildPathItemHierarchy() answers "which PathItems govern this class" — the
walk that resolves a controller's prefix, tags and security through its ancestors. It is what
the augmenter now uses in the several places that each had their own copy, and it is available
to anything else built on a Specification. Resolving path-level output no longer re-walks the
chain for every operation.
The pipeline also has a Why spec attributes? page, leading with the thing classic attributes cannot do at all — building a document from values, with nothing to scan.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.10.0...6.11.0
symfony/console moves from ^7.4 || ^8.0 to ^6.4 || ^7.0 || ^8.0, so applications on the 6.4 LTS can install current swagger-php instead of being held
symfony/console moves from ^7.4 || ^8.0 to ^6.4 || ^7.0 || ^8.0, so applications on the
6.4 LTS can install current swagger-php instead of being held back at 6.0.6. Only the CLI uses
the component — the library core, the analysers, the annotations and the processors never
touch it — so the narrow requirement was reaching consumers who never run bin/openapi.
Raised by @garak in #2180 and fixed by @yceruto in #2196, which also rebuilds the command on
configure()/execute() in place of the 7.4-only attribute syntax. GenerateInput keeps
every public property it had and gains fromInput().
additionalProperties: false as a schema by @DerManoMann in https://github.com/zircote/swagger-php/pull/2205No effect on generated output or public API.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.9.0...6.10.0
TypeMapper keeps a deprecated subclass at the old name, since a custom type resolver reaches it through AbstractTypeResolver. The other two have no sh…
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.
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:
| Was | Is |
|---|---|
OpenApi\Utils\CollectingLogger |
OpenApi\Loggers\CollectingLogger |
OpenApi\Utils\SpecificationWalker |
OpenApi\Specification\Walker |
OpenApi\Utils\TypeMapper |
OpenApi\Type\TypeMapper |
TypeMapper keeps a deprecated subclass at the old name, since a custom type resolver reaches it through AbstractTypeResolver. The other two have no shim.
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.
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)@OA\JsonContent / @OA\XmlContent through the bridge rather than by running two classic processors over a mapping it already knows (#2184)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.
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.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.8.1...6.9.0
Corrects the schema examples handling introduced in 6.8.0.
Corrects the schema examples handling introduced in 6.8.0.
6.8.0 changed generated output and the release notes did not say so. @OA\Examples nested under an @OA\Schema or @OA\Property used to emit a keyed map, which no validator accepts. It now emits the list of values JSON Schema calls for:
YoYo:
examples:
- yo:
- summary: 'the yo'
- value: YoYo
+ - YoYo
summary, description and externalValue have nowhere to go in a list and are dropped, and an example carrying no value contributes nothing. For Example Objects use a media type, parameter or header — their examples is a map and keeps every field.
@OA\Examples under a schema no longer reports a missing example key-field or a missing summary; neither reaches the output (#2177)summary is no longer required on @OA\Examples anywhere — the Example Object has no required fields in the specificationexamples now accepts plain values, in attributes and docblocks alike, and keeps the order you write when mixed with @OA\Examples:#[OA\Property(type: 'integer', examples: [80, 443])]
Items attribute's constructor docblock is repaired, so the reference page shows its declared parameter types instead of falling back to the native onesCases that used to pass in silence now warn: an @OA\Examples under a schema with no value, value and externalValue set together, and any other annotation passed as an example.
The cookbook has a new section on schema examples and how they differ from a media type's.
fix(Attributes): repair the Items constructor docblock by @DerManoMann in https://github.com/zircote/swagger-php/pull/2179
Stacked on #2178 and squash-merged, so it carries that change too — most of this release is in that commit.
Full Changelog: https://github.com/zircote/swagger-php/compare/6.8.0...6.8.1
fix(Annotations): compile a schema's examples as a list in classic too by @DerManoMann in https://github.com/zircote/swagger-php/pull/2176
Full Changelog: https://github.com/zircote/swagger-php/compare/6.7.2...6.8.0
chore(Deps): follow rector 2.6.5 rule changes and pin tooling by @DerManoMann in https://github.com/zircote/swagger-php/pull/2143
TypedList::clear() method and update tests by @DerManoMann in https://github.com/zircote/swagger-php/pull/2145phpstan/phpstan to an exact version by @DerManoMann in https://github.com/zircote/swagger-php/pull/2151$argv in the doc generator entry point by @DerManoMann in https://github.com/zircote/swagger-php/pull/2152Undefined::UNDEFINED for every mixed property by @DerManoMann in https://github.com/zircote/swagger-php/pull/2150Full Changelog: https://github.com/zircote/swagger-php/compare/6.7.1...6.7.2
Fix typo in documentation for spec attributes by @Jonezzyboy in https://github.com/zircote/swagger-php/pull/2133
Full Changelog: https://github.com/zircote/swagger-php/compare/6.7.0...6.7.1
docs(Spec): update docs about implicit Property shortcut in combination with OA\Items by @DerManoMann in https://github.com/zircote/swagger-php/pull/2
OA\Items by @DerManoMann in https://github.com/zircote/swagger-php/pull/2127Contracts namespace for all spec related interfaces by @DerManoMann in https://github.com/zircote/swagger-php/pull/2129Full Changelog: https://github.com/zircote/swagger-php/compare/6.6.0...6.7.0
fix(Spec): update remaining $ref type-hints to accept OA\Schema\Ref by @DerManoMann in https://github.com/zircote/swagger-php/pull/2119
$ref type-hints to accept OA\Schema\Ref by @DerManoMann in https://github.com/zircote/swagger-php/pull/2119OA\Property when stacking witbh OA\Schema by @DerManoMann in https://github.com/zircote/swagger-php/pull/2121contains() method by @DerManoMann in https://github.com/zircote/swagger-php/pull/2122ref with eachRef() by @DerManoMann in https://github.com/zircote/swagger-php/pull/2123ComponentIndex for lazy resolution of $ref values and component lookups by @DerManoMann in https://github.com/zircote/swagger-php/pull/2124Full Changelog: https://github.com/zircote/swagger-php/compare/6.5.3...6.6.0
feat(Spec): refactor/assembler level resolution by @DerManoMann in https://github.com/zircote/swagger-php/pull/2104
Post, 'Put, PatchandDelete` by @DerManoMann in https://github.com/zircote/swagger-php/pull/2109getDirectInterfaces into AttributeFactory by @DerManoMann in https://github.com/zircote/swagger-php/pull/2112mergeAllOf and dedupAllOfRefs logic into Refs augmenter by @DerManoMann in https://github.com/zircote/swagger-php/pull/2113php-cs-fixer rule ordered_class_elements by @DerManoMann in https://github.com/zircote/swagger-php/pull/2116OA\Schema\Ref which can be used as schema and on ref: directyl by @DerManoMann in https://github.com/zircote/swagger-php/pull/2117Full Changelog: https://github.com/zircote/swagger-php/compare/6.5.2...6.5.3
feat(Spec): improve AttributeTranslatorInterface by @DerManoMann in https://github.com/zircote/swagger-php/pull/2096
AttributeTranslatorInterface by @DerManoMann in https://github.com/zircote/swagger-php/pull/2096TokenScanner by @DerManoMann in https://github.com/zircote/swagger-php/pull/2099foreach loops with unpacking operations by @DerManoMann in https://github.com/zircote/swagger-php/pull/2102description attribute from #[OA\Property] annotation by @DerManoMann in https://github.com/zircote/swagger-php/pull/2103OpenApi31Compiler: consolidate repetitive patterns by @DerManoMann in https://github.com/zircote/swagger-php/pull/2106Full Changelog: https://github.com/zircote/swagger-php/compare/6.5.1...6.5.2
feat(Spec): widen the type of the content parameter (MediaType) to accept MediaType|array|null by @DerManoMann in https://github.com/zircote/swagger-p
content parameter (MediaType) to accept MediaType|array|null by @DerManoMann in https://github.com/zircote/swagger-php/pull/2088Specefication to build Result by @DerManoMann in https://github.com/zircote/swagger-php/pull/2093Builder sources to accept \Reflector instances too (except in CLASSIC mode) by @DerManoMann in https://github.com/zircote/swagger-php/pull/2091Items by @DerManoMann in https://github.com/zircote/swagger-php/pull/2094spec-attributes.md; content no longer relevant or needed by @DerManoMann in https://github.com/zircote/swagger-php/pull/2095Full Changelog: https://github.com/zircote/swagger-php/compare/6.5.0...6.5.1
This version introduces the spec pipeline - a new set of attributes that will replace the current (classic) annotations/attributes. It is using a radi
This version introduces the spec pipeline - a new set of attributes that will replace the current (classic) annotations/attributes.
It is using a radically different approach in how the code is organized which makes it a lot easier to maintain.
Right now, the new code is disabled and nothing changes. Key is that in order to try the new code the new OpenApi\Builder needs to be used. Again - using the Builder will, by default, change nothing and the current classic code is used.
The new Builder::setMode() method allows to run the new spec pipeline in two modes:
HYBRID: Enables spec support where found and also routes all classic annotations/attributes through the new spec pipeline.
Under the hood the classic Generator is used to load/instantiate classic annotations/attributes. Then a custom bridge translates all of those into new thin OpenApi\Spec attributes and adds them to the spec pipeline.SPEC: Only new spec attributes are processed.HYBRID is a good way to see how compatible things are and also a migration path, as a codebase could be upgrade file by file.
All spec pipeline related commits have been omitted from the change list for clarity and brevity. Going forward these will be marked as feat(Spec): and listed as all other changes.
All current tests pass in HYBRID mode. However, there hasn't been any testing on actual projects yet. Testing the new code in hybrid mode on existing projects and feedback would be greatly appreciated.
CustomName/Blink with CustomName-Blink in examples and annotations by @DerManoMann in https://github.com/zircote/swagger-php/pull/2069Full Changelog: https://github.com/zircote/swagger-php/compare/6.4.0...6.5.0
feat: add Builder as unified entry point by @DerManoMann in https://github.com/zircote/swagger-php/pull/2044
Full Changelog: https://github.com/zircote/swagger-php/compare/6.3.2...6.4.0
Remove dev dep composer/package-versions-deprecated by @DerManoMann in https://github.com/zircote/swagger-php/pull/2049
Utils namespace by @DerManoMann in https://github.com/zircote/swagger-php/pull/2041multiline_comment_opening_closing rule by @DerManoMann in https://github.com/zircote/swagger-php/pull/2043composer/package-versions-deprecated by @DerManoMann in https://github.com/zircote/swagger-php/pull/2049Full Changelog: https://github.com/zircote/swagger-php/compare/6.3.1...6.3.2
fix: add native array|string type to Serializer::doDeserializeBaseProperty() by @DerManoMann in https://github.com/zircote/swagger-php/pull/2036
Utils\DocBlockParser by @DerManoMann in https://github.com/zircote/swagger-php/pull/2038TokenScannerand other utils to OpenApi\Utils namespace by @DerManoMann in https://github.com/zircote/swagger-php/pull/2039Full Changelog: https://github.com/zircote/swagger-php/compare/6.3.0...6.3.1
fix: PHP 8.5 deprecation for null as array offset by @DerManoMann in https://github.com/zircote/swagger-php/pull/2032
Full Changelog: https://github.com/zircote/swagger-php/compare/6.2.0...6.3.0
Make AbstractAnnotation::$_context non-nullable by @krissss in https://github.com/zircote/swagger-php/pull/2008
AbstractAnnotation::$_context non-nullable by @krissss in https://github.com/zircote/swagger-php/pull/2008GeneratorAwareInterface::setGenerator() and align related code by @DerManoMann in https://github.com/zircote/swagger-php/pull/2013Full Changelog: https://github.com/zircote/swagger-php/compare/6.1.2...6.2.0
Handle parameter dockblocks by @DerManoMann in https://github.com/zircote/swagger-php/pull/1998
array<K, V> to type: object + additionalProperties by @krissss in https://github.com/zircote/swagger-php/pull/2003Full Changelog: https://github.com/zircote/swagger-php/compare/6.1.1...6.1.2
Add PHP 8.6 to build matrix by @DerManoMann in https://github.com/zircote/swagger-php/pull/1986
Full Changelog: https://github.com/zircote/swagger-php/compare/6.1.0...6.1.1
Bump crazy-max/ghaction-github-pages from 4 to 5 by @dependabot[bot] in https://github.com/zircote/swagger-php/pull/1970
ext-json by @DerManoMann in https://github.com/zircote/swagger-php/pull/1974bin/openapi to Symfony Console by @yceruto in https://github.com/zircote/swagger-php/pull/1977Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.6...6.1.0
Centralize all pure JSON Schema properties by @DerManoMann in https://github.com/zircote/swagger-php/pull/1960
Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.5...6.0.6
Fix v6 migration typo: TypeInfoTypeResolver is the default resolver by @thePanz in https://github.com/zircote/swagger-php/pull/1951
npm tools deps by @DerManoMann in https://github.com/zircote/swagger-php/pull/1954deepObject parameter to attribute Parameter by @DerManoMann in https://github.com/zircote/swagger-php/pull/1957Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.4...6.0.5
Improve phpstan config by @DerManoMann in https://github.com/zircote/swagger-php/pull/1928
master by @DerManoMann in https://github.com/zircote/swagger-php/pull/1938Generator::isDefault() where appropriate by @DerManoMann in https://github.com/zircote/swagger-php/pull/1940TypeInfoTypeResolver by @DerManoMann in https://github.com/zircote/swagger-php/pull/1945Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.3...6.0.4
Update readme by @DerManoMann in https://github.com/zircote/swagger-php/pull/1922
Generator default config and allow to show in CLI by @DerManoMann in https://github.com/zircote/swagger-php/pull/1925Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.2...6.0.3
Skip type resolving on Schema with items set (#1916) by @DerManoMann in https://github.com/zircote/swagger-php/pull/1916
Schema with items set (#1916) by @DerManoMann in https://github.com/zircote/swagger-php/pull/1916Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.1...6.0.2
Update phpunit deps and some related issues by @DerManoMann in https://github.com/zircote/swagger-php/pull/1909
phpunit deps and some related issues by @DerManoMann in https://github.com/zircote/swagger-php/pull/1909rector/rector dependency to ^2.3.1 by @DerManoMann in https://github.com/zircote/swagger-php/pull/1913Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.0...6.0.1
All 5.x deprecations have been removed
radebatz/type-info-extras is now a required dependencyTypeInfoTypeResolver is now the default^8.0 to deps list by @DerManoMann in https://github.com/zircote/swagger-php/pull/1854method_exists checks by @DerManoMann in https://github.com/zircote/swagger-php/pull/1862doctrine/annotations by @DerManoMann in https://github.com/zircote/swagger-php/pull/1870'3.1.2' and '3.2.0' by @DerManoMann in https://github.com/zircote/swagger-php/pull/1871patternProperties to attributes by @DerManoMann in https://github.com/zircote/swagger-php/pull/1876$additionalProperties by @DerManoMann in https://github.com/zircote/swagger-php/pull/1878jsonSerialize() return type by @DerManoMann in https://github.com/zircote/swagger-php/pull/1883summary/description default value to support null as user provided value by @DerManoMann in https://github.com/zircote/swagger-php/pull/1886Tag annotations by @DerManoMann in https://github.com/zircote/swagger-php/pull/1893query operation by @DerManoMann in https://github.com/zircote/swagger-php/pull/1894unevaluatedProperties support by @DerManoMann in https://github.com/zircote/swagger-php/pull/1907Full Changelog: https://github.com/zircote/swagger-php/compare/5.7.3...6.0.0
Minor annotation factory cleanup by @DerManoMann in https://github.com/zircote/swagger-php/pull/1895
Tag annotations by @DerManoMann in https://github.com/zircote/swagger-php/pull/1893query operation by @DerManoMann in https://github.com/zircote/swagger-php/pull/1894Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.0-RC3...6.0.0-RC4
Add some type resolver details to Readme by @DerManoMann in https://github.com/zircote/swagger-php/pull/1867
doctrine/annotations by @DerManoMann in https://github.com/zircote/swagger-php/pull/1870'3.1.2' and '3.2.0' by @DerManoMann in https://github.com/zircote/swagger-php/pull/1871patternProperties to attributes by @DerManoMann in https://github.com/zircote/swagger-php/pull/1876$additionalProperties by @DerManoMann in https://github.com/zircote/swagger-php/pull/1878jsonSerialize() return type by @DerManoMann in https://github.com/zircote/swagger-php/pull/1883summary/description default value to support null as user provided value by @DerManoMann in https://github.com/zircote/swagger-php/pull/1886Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.0-RC2...6.0.0-RC3
Methods SplObjectStorage::attach(), detach & contains() are deprecated since PHP 8.5. by @yblatti in https://github.com/zircote/swagger-php/pull/1865
^8.0 to deps list by @DerManoMann in https://github.com/zircote/swagger-php/pull/1854method_exists checks by @DerManoMann in https://github.com/zircote/swagger-php/pull/1862Full Changelog: https://github.com/zircote/swagger-php/compare/6.0.0-RC1...6.0.0-RC2
Backport latest changes of LegacyTypeResolver from v6 by @DerManoMann in https://github.com/zircote/swagger-php/pull/1851
Full Changelog: https://github.com/zircote/swagger-php/compare/5.7.3...6.0.0-RC1
[Backport #1962 to 5.x] Refactor AbstractAnnotation::identity() by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1963
Full Changelog: https://github.com/zircote/swagger-php/compare/5.8.2...5.8.3
[Backport #1954 to 5.x] Update npm tools deps by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1955
npm tools deps by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1955deepObject parameter to attribute Parameter by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1958Full Changelog: https://github.com/zircote/swagger-php/compare/5.8.1...5.8.2
[Backport #1936 to 5.x] Schema type check type array by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1937
Generator::isDefault() where appropriate by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1941Full Changelog: https://github.com/zircote/swagger-php/compare/5.8.0...5.8.1
[Backport #1907 to 5.x] Add support for 3.1 unevaluatedProperties support by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1908
unevaluatedProperties support by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1908Items' case to NestedSchema scratch fixture by @DerManoMann in https://github.com/zircote/swagger-php/pull/1933Full Changelog: https://github.com/zircote/swagger-php/compare/5.7.8...5.8.0
[Backport #1895 to 5.x] Minor annotation factory cleanup by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1896
Tag annotations by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1897query operation by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1898rector/rector dependency to ^2.3.1 by @github-actions[bot] in https://github.com/zircote/swagger-php/pull/1914rector/rector dependency to ^2.3.1" by @DerManoMann in https://github.com/zircote/swagger-php/pull/1915Full Changelog: https://github.com/zircote/swagger-php/compare/5.7.7...5.7.8
One column per quarter.