Map default error status code in Ballerina to OpenAPI spec generation

[lnash94]

Description:
The purpose is to map default error code details when the user doesn't provide a specific return type in the resource.

Task 01: Updating the error code when the resource has nil return.
Task 02: Updating status code details when the resource has a specific return type with nil type
example for task 02:

 //This will return 202 -Accepted, 400 -Bad Request, 404-Not Found
    resource function delete name(string id) returns http:NotFound? {
    };

[lnash94]

Task 01: Updating the error code when the resource has nil return.
Currently, the tool maps the HTTP status code '202 Accepted' when there is a nil return. With this improvement, it will also map to '400 Bad Request' when there are resources with the path, query, header, or requestBody, resulting in a nil return.
Ballerina code:

import ballerina/http;

service / on new http:Listener(9090) {
    //with query parameter
    resource function delete name(string id) {
    };
    // with path parameter
    resource function post name/[string id]() {
    };
    //with header parameter
    resource function get name(@http:Header string header) {
    };
    //with requestBody
    resource function put name(@http:Payload string payload) {
    };

Expected generated yaml

paths:
  /name:
    get:
      operationId: getName
      parameters:
      - name: header
        in: header
        required: true
        schema:
          type: string
      responses:
        "202":
          description: Accepted
        "400":
          description: BadRequest  
    put:
      operationId: putName
      requestBody:
        content:
          text/plain:
            schema:
              type: string
      responses:
        "202":
          description: Accepted
        "400":
          description: BadRequest   
    delete:
      operationId: deleteName
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        "202":
          description: Accepted
        "400":
          description: BadRequest   
  /name/{id}:
    post:
      operationId: postNameId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        "202":
          description: Accepted
        "400":
          description: BadRequest   
components: {}

Note: Fix should include for all GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

@shafreenAnfar , @TharmiganK appreciate input regarding this.

[lnash94]

Task 02: Updating status code details when the resource has a specific return type with nil type

service /payloadV on new http:Listener(9090) {
    resource function get path() returns http:NotFound? {
    }
    resource function get path_with_query(string id) returns http:NotFound? {
    };
   ...
}

expected response mapping

paths:
  /path:
    get:
      operationId: getPath
      responses:
        "202":
          description: Accepted
        "404":
          description: NotFound
  /path_with_query:
    get:
      operationId: getPathWithQuery
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        "202":
          description: Accepted
        "400":
          description: BadRequest
        "404":
          description: NotFound

[TharmiganK]

Both mappings are correct here. What about this scenario when we return a data type with nil?

service on new http:Listener(9090) {
    resource function get path1() returns string? {}
    
    resource function get path2(string id) returns Student|http:NotFound? {}
}

I do not think this is a practical case, but a possible scenario

[TharmiganK]

Another most common scenario to have a nil return type is when we are using a http:Caller. In that case do we do response mapping?

We still represent the possible return types of the caller using the http:CallerInfo annotation

service on new http:Listener(9090) {
     resource function get path(http:Caller caller) returns error? {}
}

Note that when we use http:Caller in a http resource, then we only allow the return type to be error?.

[lnash94]

Another most common scenario to have a nil return type is when we are using a http:Caller. In that case do we do response mapping?

We still represent the possible return types of the caller using the http:CallerInfo annotation

service on new http:Listener(9090) {
     resource function get path(http:Caller caller) returns error? {}
}

Note that when we use http:Caller in a http resource, then we only allow the return type to be error?.

Currently, the tool doesn't map details regarding the http:Caller, we will address this particular scenario once we give support for http:Caller mapping.

[lnash94]

Both mappings are correct here. What about this scenario when we return a data type with nil?

service on new http:Listener(9090) {
    resource function get path1() returns string? {}
    
    resource function get path2(string id) returns Student|http:NotFound? {}
}

I do not think this is a practical case, but a possible scenario

@TharmiganK For the mentioned scenarios, it will take a status code relevant to the string payload.
expected code

/path1:
    get:
      operationId: getPath
      responses:
        "200":
          description: Ok
          content:
            text/plain:
              schema:
                type: string
        "202":
          description: Accepted
  /path2:
    get:
      operationId: operation2
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Ok
          content: 
            application/json:
               schema:
                $ref: "#/components/schemas/Student"
        "202":
          description: Accepted
        "400":
          description: BadRequest
        "404":
          description: NotFound

If the given type is POST, it will return 201 - Created instead of 200

When the given sample with POST

service on new http:Listener(9090) {
    resource function post path1() returns string? {}
    
    resource function post path2(string id) returns Student|http:NotFound? {}
}

expected yaml code

/path1:
    post:
      operationId: postPath
      responses:
        "201":
          description: Created
          content:
            text/plain:
              schema:
                type: string
        "202":
          description: Accepted
  /path2:
    post:
      operationId: operation2
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        "201":
          description: Created
          content:
            application/json:
               schema:
                $ref: "#/components/schemas/Student"
        "202":
          description: Accepted
        "400":
          description: BadRequest
        "404":
          description: NotFound