Can org.eclipse.microprofile.openapi.models.OpenAPI and its "children" return `null` on getters?

[hbelmiro]

I couldn't find in the docs whether OpenAPI's getters can return null. For example, could the following code throw a NullPointerException?

    private static Optional<Schema> getSchemaRef(String id, OpenAPI openAPI) {
        return Optional.ofNullable(openAPI.getComponents().getSchemas().get(id));
    }

It would be helpful to have it explicitly stated in the #getComponents() and #getSchemas() Javadoc whether they can or cannot return null values, or if it's up to the implementation."

[Azquelt]

I agree that the Javadoc should state where null may be returned or passed as a parameter and what it means. We should add that in the next release.

To my eye, the fact that the model API has separate set and get methods for collections suggests that null is permitted and may be returned.

In a Security Requirement Object, there's a difference between a key being present and set to an empty array vs. not being present which would make changing the API to be null free API more difficult.

There are a few other things the model API javadoc also doesn't make clear:

• We also don't state whether you can call e.g. getComponents, make changes to it and expect your changes to be reflected in the model or whether getComponents returns a copy or an immutable object.
• We don't provide a way to copy or clone a model object

[Azquelt]

Unfortunately, I've run out of time to tackle this before the next release.

My assumption from looking at the way the API is structured is that null can be passed in and returned anywhere, but I would want to check whether that behaviour is consistent with all available implementations.

If it is, then we could make the documentation change in the a minor release. If it isn't, then we'd need to come to some kind of agreement over how it should behave and agree to specify that and make our implementations consistent.