Restructure Ballerina resource path parameters to OAS module

[SachinAkash01]

Description:

Need to restructure the code base of resource path parameter mapping from Ballerina to OpenAPI specification.
Parent: #5055

When the code is properly restructured, the resource path parameters are reflected in the OpenAPI specification as follows,

Sample Ballerina code:

# Description of the function.
#
# + title - Title of the album
# + return - Return description
resource function get albums/[string title]() {}

OpenAPI specification:

paths:
  /albums/{title}:
      get:
        summary: Description of the function
        operationId: getSongsAlbumId
        parameters:
        - name: title
          in: path
          description: Title of the album
          required: true
          schema:
            type: string

Rest parameters in the resource path:

Ballerina supports rest parameters. There cannot be another parameter after a rest parameter in the resource path.
Utilizing rest parameters in the path of a resource function acts as a list. For example:

resource function get users/[int... id]() {}

This allows us to send a request like:
GET users/id1/id2/id3

In the resulting URL, these parameters are concatenated with %2F (encoded value for /), and it looks like:
http://{hostName}:{port}/users/id1%2Fid2%2Fid3

Parameter serialization is used in OpenAPI specification to support arrays and objects in operation parameters (path, query, header, and cookie) and lets you specify how these parameters should be serialized. The serialization method is defined by the style and explode keywords.

After having some discussions, we decided to omit the mapping of the entire operation for now if there is a rest parameter in the resource path and provide users with a warning since we cannot properly reflect rest parameters in the OpenAPI specification!

Note: we can map the operation without path parameters when there is a rest parameter in the resource path, but then the OpenAPI spec will show incorrect information regarding that operation.

[SachinAkash01]

Meeting date: 27/11/2023
Attendees: @shafreenAnfar @lnash94 @SachinAkash01

Had a discussion on the above concerns regarding rest parameters in the resource path and came up with the following decisions:

Ballerina service to OAS

• Map string type rest parameters in resource paths to wildcard paths in OpenAPI specification.

resource function get albums/[string... title]() {}

paths:
  /albums/*:
    get:
      operationId: getAlbumsTitle
      responses:
        "202":
          description: Accepted

• Skips mapping operations with non-string rest parameters in the resource path to OAS.

OAS to Ballerina service

• Generate Ballerina service with a resource featuring a string rest parameter in its path when there is a wildcard path in the OpenAPI specification.

[commonism]

OAS3 does not have a notion of "wildcard path" for PathItems, so this description document will not work for anything outside of ballerina.

Why not just serialize (string) array parameters in a OAS3 standardized way instead?
Using . would do for simple encoding.

[SachinAkash01]

OAS3 does not have a notion of "wildcard path" for PathItems, so this description document will not work for anything outside of ballerina.

Why not just serialize (string) array parameters in a OAS3 standardized way instead? Using . would do for simple encoding.

@commonism thanks for the clarification regarding "wildcard path" limitation in OAS3. We initially considered parameter serialization as a workaround. But found that none of the supported encodings aligns with our specific scenario:
GET users/id1/id2/id3 -> /users/id1%2Fid2%2Fid3
Because of that, we thought of taking a different approach for this rather than serializing.

@shafreenAnfar @lnash94 as discussed, we will omit mapping of the entire operation if there is a rest parameter in the resource path and provide users with a warning since we have a limitation with the "wildcard path" in OAS3.

[commonism]

I'm with the client side of the OpenAPI ecosystem, and I really encourage you to design ballerina REST encoding compliant to the OAI specification.

Non compliant will result in "can not be used with any existing tooling and requires manual intervention for data serialization/validation".

There is no alternative to OAI, not being compatible as a web/rest framework begs many questions wrt. to the design decisions and the relevance of the framework.

[TharmiganK]

Fixed via ballerina-platform/openapi-tools#1564