Update Swagger UI endpoints to include all parameters, specifically for multiple communities

[chuang-CE]

The endpoint:
POST /resources/organizations/{organization_id}/documents
is missing definition for community_name, which the user is supposed to append to the front of this endpoint if the community they want to publish as is not set as the default envelope community. This needs to be made obvious to users when they read through the Swagger UI. If any other endpoints are missing optional parameters, add them in as well.

[excelsior]

@chuang-CE I have a suggestion: What if instead of having two versions of such endpoints in Swagger—one for the default community and the other for an explicit community—e.g.

1. GET /foo
2. GET /{community_name}/foo

we only leave the latter, but make the community_name parameter optional. If it's omitted, the default community will be assumed and it will act as the former above. That way we reduce the number of definitions in Swagger almost by a half.

[rohit-joy]

Personally, the concept of default community from a Registry is an overreach.

Rather, I'd prefer GET /community/{community_name}/foo to be the only endpoints.

Let the host of the Registry instance rewrite their custom URLs to their instance such as /{community_name}/foo or /foo into /community/{community_name}/foo if they so choose. For example, if CE wants a default community concept, CE can choose to rewrite such URLs at the gateway for example.

Feel free to create a separate issue for what I am discussing above and continue with a short term mitigation with @chuang-CE.

Another alternative: Generally, when optional things come up, it should take our attention towards query-string parameters.

[chuang-CE]

@chuang-CE I have a suggestion: What if instead of having two versions of such endpoints in Swagger—one for the default community and the other for an explicit community—e.g.

1. GET /foo
2. GET /{community_name}/foo

we only leave the latter, but make the community_name parameter optional. If it's omitted, the default community will be assumed and it will act as the former above. That way we reduce the number of definitions in Swagger almost by a half.

I do agree that we shouldn't just double the number of definitions in Swagger. I also agree with Rohit's statement about using query-string parameters for the community name. Can we go with that approach instead? Ex:
GET /foo?community_name={community_name}

[jeannekitchens]

@edgarf @excelsior please reply to the comments here.

[excelsior]

@chuang-CE @rohit-joy

Both suggested improvements would break the API. We can implement one of them (I, too, prefer the latter), but only in the next version of the API, while keeping the current version intact.

Anyway, that's well out of scope of this task which is about revising and improving the Swagger UI. My previous question was solely about reducing the number of defs by half without making any drastic changes to the API.

So if an endpoint has two signatures (short for the default community and full for any), are you OK with only seeing the full signature for the sake of brevity?

[khasan786]

@chuang-CE @rohit-joy Can one of you please address the latest question posted by @excelsior above so we can bring this issue to a mutually agreeable conclusion?.

[rohit-joy]

@excelsior Why does the query string option break the API spec that would require a new API version?

[khasan786]

@excelsior Can you please address the question posted by @rohit-joy above?

[excelsior]

@chuang-CE @rohit-joy Currenty, we have two kinds of signatures for most of the endpoints:

1. /{community_name}/foo, which has an explicit community name in it.
2. /foo, which implicitly uses the default community and is equivalent to /<DEFAULT COMMUNITY NAME>/foo.

Just to make sure we're on the same page, you guys are suggesting to only support the latter kind of signature with an optional community_name query parameter. Meaning that the former shouldn't be supported anymore, right?

If it still has be supported, then it's hardly a simplification, quite contrary. If it doesn't then the API will become broken. However, if we consider the API to be unstable, then it's perfectly fine to drop the explicit signature, I guess.

If we want to do that, let's open a separate issue for it, because this one is about improving the docs, without any changes to the API.

[khasan786]

@rohit-joy & @chuang-CE Please advise if we should create a separate issue at this time as suggested by @excelsiur above.

[khasan786]

@rohit-joy & @chuang-CE Just following up on my question above if we should create a separate issue at this point as suggested by @excelsiur above or if there is a different plan of action to be adopted from CE's perspective?..

[excelsior]

@chuang-CE The Swagger updates regarding the missing endpoints are ready for review on staging:

https://staging.credentialengineregistry.org/swagger/index.html