zircote/swagger-php 7.1.0

on PHP Packagist

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.

Changed output

• A path parameter defaults to required: true, as OpenAPI requires. A path parameter set to anything else logs a warning (#2338)
• A class with more than one component in a bucket no longer stands for whichever was indexed last. A $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)

New

• Component namer. 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)
• Describing a class more than once. A component can carry a key of its class plus qualifiers, for example one per serialization group, and a Schema\Ref with the same qualifiers references it. In an augmenter, ComponentIndex::findByKey() and findAllByKey() look components up by key (#2342, docs)
• Keeping a component. 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)

Fixes

The fixes from 6.20.1 are in 7.1 as well: #2328, #2330, #2331, #2333 and #2334.

Deprecated, removed in 8.0

• ComponentIndex::buildRefMap(). Use ComponentIndex::findByKey(), which takes the bucket a use means
• OpenApi31Compiler::refString(). Use RefInterface::getRefValue() on the attribute that holds the ref

Docs

• A cookbook recipe for building parts of a document to use in another one (#2336)
• openapi-json-schema is listed on the related projects page, and the openapi-router entry now says it reads spec attributes (#2340, #2332)

What's Changed

• docs(Related): openapi-router reads spec attributes by @DerManoMann in #2332
• fix(Spec): preserve inferred empty object defaults by @krissss in #2328
• fix(Spec): infer typed PHPDoc examples by @krissss in #2330
• fix(Augmenter): resolve class names in a nested schema's discriminator mapping by @EgorGruzdev in #2331
• fix(Specification): read a component key assigned after construction by @DerManoMann in #2333
• fix(Analysers): a class-level attribute that no parent has room for goes to the root by @DerManoMann in #2334
• docs(Cookbook): build parts of a document for another one by @DerManoMann in #2336
• feat(Augmenter): keep a component marked to be kept in Cleanup by @DerManoMann in #2339
• docs(Related): list openapi-json-schema by @DerManoMann in #2340
• feat(Builder): name components through a replaceable namer by @DerManoMann in #2341
• fix(Augmenter): default a path parameter to required and warn about one that is not by @DerManoMann in #2338
• feat(Specification): look components up by a key of class and qualifiers by @DerManoMann in #2342
• refactor(Spec): give attributes that carry a ref an interface by @DerManoMann in #2343

New Contributors

• @EgorGruzdev made their first contribution in #2331

Full Changelog: 7.0.0...7.1.0