Questions about org.eclipse.microprofile.openapi.models.PathItem

I am new to the Microprofile project, I hope this is the appropriate channel to start a discussion.

How definitive are the model interfaces introduced with version MicroProfile release 3.1? I understand that Swagger Core was used as reference, but maybe some stuff can be improved when establishing a standard.

Today I have worked a lot with PathItem and Operation (I work with swagger-core) and I was curious to see how you guys did solve this.

Here 2 questions about org.eclipse.microprofile.openapi.models.PathItem.

Thank you in advance for the discussion.

---

Question 1: why are the convenience methods that provides all operations as list or as map called readOperations() and readOperationsMap():

https://github.com/eclipse/microprofile-open-api/blob/bffd7ace546bd964cb46d29dcf2114c8ac28fe80/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java#L266-L278

I like the way the Kaizen-Parser solves this by providing a map (they do not have the enum for HTTP operation type):

	Map<String, Operation> getOperations();

(source)

If we take the best of both words:

Map<PathItem.HttpMethod, Operation> getOperations();

With the constraint that the returned Map should never be null and that the map is a read-only access to the operations. (could be indicated in the Javadoc)

If you just want the collection of operations getOperations().values() can be called. I do not think that a method returning List<Operation> is requested.

---

Question 2: In Swagger-Core the String path of an PathItem is an important information that belongs in my opinion to the PathItem object, but that is missing the Operation object.

To access to this information you need the corresponding Entry<String, PathItem> of the Paths map holding the PathItem.

Because this information is not present, you need always to pass it with in each PathItem instance in of your methods:

void printOperationsInfo(String path, PathItem path);

Or to have your own holder class:

static class PathItemWithPath {
    final String pathString;
    final PathItem path;

    public PathItemWithPath(final String pathString, final PathItem path) {
        super();
        this.pathString = pathString;
        this.path = path;
    }

The Kaizen-Parser Model did solve this with:

	String getPathString();

(source)

Maybe the wording is not ideal, but the information is really important when you manipulate PathItem instances.

[arthurdm]

hey @jmini - welcome to MicroProfile and thanks a lot for your feedback! It’s really cool to merge best practices from industry leaders like Kaizen and Swagger, so definitely a good direction.

I agree with both your suggestions. For #1 I suspect that’s a historic serialization/deserialization issue where there wasn’t a field called operations so getOperations was ruled out - but whatever historic reasoning was used, I don’t see any issues with the proposal.

For #2, we have Paths which uses name as the path string, so I would suggest we add String getName(); just for consistency with its parent model.

If you would like to submit a PR for this, I will gladly review.

Thanks.

[jmini]

New issue: https://github.com/eclipse/microprofile-open-api/issues/264

the issue is only a draft, I never took the time to investigate the proposed concept completely. But I am sure that the concept is necessary. It simplifies the manipulation code a lot.