Models: do we need the interfaces extending Map?

There are several model interfaces: Paths, ServerVariables, Content, APIResponses, Scopes, Callback, that extends, Map<String, T>

My points are:

1/ Those Interfaces are really strange, when working with it, you never can not use stuff like:

• Arrays.asList(..)
• Streams + Collectors

2/ To implement #240 we might need to remove those interface. How do you create an immutable version of Paths

3/ The KaiZen-Parser models do not use such a construct.

[jmini]

PR for 1.1: #283 PR for 2.0: #287

[jmini]

In my opinion we do not need to have both:

Paths addPathItems(Map<String, PathItem> items);
void setPathItems(Map<String, PathItem> items);

This will be confusing.

---

The builder pattern make sense for the single add item, using this method: addPathItems(String, PathItem)

See this example (from the TCK):

.paths(OASFactory.createObject(Paths.class)
    .addPathItem("/modelReader/airlines", OASFactory.createObject(PathItem.class)
        .GET(OASFactory.createObject(Operation.class)
            .summary("Retrieve all available airlines")
            .operationId("getAirlines")
            .responses(OASFactory.createObject(APIResponses.class)
                .addAPIResponse("404", OASFactory.createObject(APIResponse.class)
                    .description("No airlines found")
                    .content(OASFactory.createObject(Content.class)
                        .addMediaType("n/a", OASFactory.createObject(MediaType.class)))))))
    .addPathItem("/availabilityModel", OASFactory.createObject(PathItem.class)
        .GET(OASFactory.createObject(Operation.class)
            .tags(new ArrayList<String>())
                .addTag("Availability")
            .summary("TEST SUMMARY")
            .operationId("getTestFlights")
//...

I do not see the benefit of having a builder pattern for the Map. Even with the new builder method for Maps (java.util.Map.of(k1, v1, k2, v2) - Java 10), I think that the single add builder method is more readable.

---

My recommendation, add a simple setter like this:

void setPathItems(Map<String, PathItem> items);

If we use a setter method, then it is natural to have a void return value.