OpenAPI-Specification | The OpenAPI Specification Repository | REST library

format: binary had limitations when you needed to specify both the media type and the encoding. Specifically, this example from OAS 3.0.2:

My reading of the spec is that they are not ambiguous, because one is more concrete than the other. The more concrete one takes precedence if the {petId} parameter value is set to _search.

I don't think a reputable source is available on this subject but i do have long experience with frameworks, abstract user interfaces and php and created MetaClass Tutorial Api Platform so i will try to answer your question myself.

The tutorial aims to cover the common ground of most CRUD and Search apps for both an api platform api and a react client generated with the api platform client generator. The tutorial does not cover inheritance and polymorphism because i do not think it occurs in many CRUD and Search apps but it adresses many aspects that do, for an overview see the list of chapters in the readme of the master branch. Api Platform offers a lot of generic functionality for the api of such apps out of the box that only needs to be configured for specific resources and operations. In the react branches this led to recurring patterns and refactoring into common components and eventually to an extended react client generator to accompany the tutorial. The scheme of serialization groups in this answer is a bit more generic because my understanding of the subject has improved over time.

Your classes worked out of the box on Api Platform 2.6 except for the repository classes that where not included. I removed them from the annotation as right now none of their specific methods seem to be called. You can allways add them again when your need them.

Against the common preference for REST in general to use a single endpoint /animals i chose for individual ones for /dogs, /cats, and /mice because:

1. Api Platform identifies instances of resource classes by iri's that refer to these specific endpoints and inludes them as values of @id whenever these instances are serialized. The client generater, and i suppose the admin client too, depend on these endpoints to work for crud operations,
2. With Api Platform specific post operations work out of the box with doctrine orm. An endpoint /animals would require a custom Denormalizer that can decide which concrete class to instantiate.
3. With serialization groups specific end points give more control over serializations. Without that is it hard to get serialization compatible with the way it is done in chapter 4 of the tutorial,
4. In many of the extension points of Api Platform it is easy to make things work for a spefic resource and all examples in the docs make use of that. Making them specific for the actual concrete subclass of the object at hand is undocumented and may not allways be possible.

I only include the /animals get collection operation because that allows the client to retrieve, search and sort a polymophic collection of animals in a single request.

In line with chapter 4 of the tutorial i removed the write annotation groups. Api Platforms deserialization already allows the client to only include those properties with post, put and patch that hold data and are meant be set, so the only purpose of deserialization groups can be to disallow certain properties to be set through (certain operations of) the api or to allow the creation of related objects through nested documents. When i tried to add a new cat by posting it as value of $ateByCat of a mouse i got error "Nested documents for attribute "ateByCat" are not allowed. Use IRIs instead." The same happened with adding one through Dog::$catsChased, so security by operation with certain roles granted does not seem to be compromised without write annotation groups. Seems like a sound default to me.

I added a ::getLabel method to Animal to represent each by a single string (annotated as http://schema.org/name). Basic CRUD and Search clients primarily show a single type of entities to the user and represent related entities this way. Having a specific schema.org/name property is more convenient for the client and making it a derived property is more flexible then then adding different properties depending on the type of entity. The label property is the only property that is added to the "related" group. This group is added to the normalization context of each type so that for the "get" operations of Cat, Doc and Mouse it is the only property serialized for related objects:

From this bug thread:

What we meant here (and if needed, can clarify further) is that the value given here is the actual value of the example. It is not to be further parsed by tooling. So documentation or mocking services should not try to parse the $ref's before further 'using' them.

The reason behind is exactly $ref's. We can't distinguish when the end user would want to use $ref as a resolved reference and when they'd want to use it as a literal value (which is a very valid case). As such, we decided that the examples would be non-parsed literal values. At the moment, there's no way to have parsable examples, as external examples are literal values as well.

My goal is to get a list of operationIds

From you description, you only want the operationId values under .path, so you could write:

The contents provided by the toString() method is some convenience feature for the developer. It does not necessarily produce valid JSON representation of the object. You should use a JSON serializer to serialize your JAVA object into a JSON string. This can for example be done with the help of the Gson library.

The security entry mustn't be "in" the x-google-backend, but bellow the get:. Like this.

A LoopBack 4 application is still a Node.js application. Hence, you can make the request directly in the Controller via the built-in http module, or by importing another package (e.g. request).

From there, the result can be mutated (if needed) then returned within the Controller.

If API is commonly-used across numerous Controllers, then it is recommended to refactor the requests behind a Service. Services benefit from being bootable at runtime via this.boot() and injectable into controllers using @inject or @service.

The version 2.7.0 added this feature.

To add this field externalDocs, you can use the extensions method from the Docket: