[Proposal] Convert the OAS to Ballerina-friendly naming conventions

Summary

The OpenAPI Specification (OAS) is a widely adopted standard for defining RESTful APIs. However, the naming conventions used in OAS often differ from those preferred in Ballerina. To enhance the usability and readability of OAS definitions in Ballerina, it is essential to adapt the OAS naming conventions to align with Ballerina's conventions. This proposal outlines the approach for modifying the OAS to conform to Ballerina naming conventions.

Goals

Convert the OAS with Ballerina-friendly naming conventions to generate clients and services that are aligned with the Ballerina naming conventions.

Motivation

[1] Referring to the below OAS sample:

openapi: "3.0.0"
info:
  version: v3
  title: Karbon API 3.0
servers:
  - url: http://localhost:9090/v1
paths:
  /customer/groups:
    get:
      …
      parameters:
        - name: "customer-group" \\query param
          in: query
          schema:
            type: string
      responses:
        '200':
          description: successful
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/karbon.Api.Contacts.V2.ClientGroupSummaryDTO"
components:
  schemas:
    karbon.Api.Contacts.V2.ClientGroupSummaryDTO:  \\schema types
      type: object
      properties:
        full-name:  \\property-name
          type: string
        phone-number:  \\property-name
          type: string

The component schema name karbon.Api.Contacts.V2.ClientGroupSummaryDTO is hard to understand and doesn't follow Ballerina's naming rules.
There are properties called full-name, and phone-number in the object, which also don't match Ballerina's naming style.
To make it work in Ballerina, we need to escape the special characters:
- karbon.Api.Contacts.V2.ClientGroupSummaryDTO ----> karbon\.Api\.Contacts\.V2\.ClientGroupSummaryDTO
- full-name ----> full\-name

Generated Ballerina Code:

public type karbon\.Api\.Contacts\.V2\.ClientGroupSummaryDTO record { 
     string full\-name; 
     string phone\-number; 
}
…
resource isolated function get customer/groups(map<string|string[]> headers = {}, *GetClientQueries queries) returns karbon\.Api\.Contacts\.V2\.ClientGroupSummaryDTO|error {
       ...
   }
}

However, when using this generated record, users may face code readability issues. The escaped characters make the code harder to read and understand. This can lead to confusion and potential mistakes during development. By addressing this issue we aim to generate Ballerina-friendly code using OAS by applying modifications to the user-given OAS.

Description

The proposed solution is modifying the OAS with the Ballerina-friendly naming conventions for the below-mentioned areas,

Every OAS schema is named under the component sections and parameter names.
Query Parameters and Object property names can not be modified because they are wired to data-binding directly, therefore we need to provide some extensions to the OAS to map the details while data-binding,
- Adding extension attribute x-ballerina-name to the OAS query parameters and OAS property names

openapi: "3.0.0"
info:
 ...
paths:
  /customer/groups:
    get:
      …
      parameters:
        - name: "customer-group"
          x-ballerina-name: “customerGroup”   <--- query name extension
          in: query
          schema:
            type: string
      responses:
        '200':
          description: successful
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/KarbonApiContactsV2ClientGroupSummaryDTO"
components:
 schemas:
   KarbonApiContactsV2ClientGroupSummaryDTO: // Type Name
     type: object
     properties:
       full-name: //property name
         type: string
         x-ballerina-name: fullName          <--property name extension 
       phone-number:
         type: string
         x-ballerina-name: phoneNumber

We are providing two options to the user as a deliverable,

If the user is interested in the returned OAS as a deliverable, we introduce a sub-command to return the modified OAS mentioned above.[2]

$ bal openapi sanitize \<yaml file>

When the user needs to generate a client/service which engages that modified OAS, deliverable is client /service Ballerina code.
- When we use the modified OAS according to the Ballerina conventions, we will generate the following Ballerina code as a client.

type KarbonApiContactsV2ClientGroupSummaryDTO record { 
    @http:Field: {name: "field-name"}
        string fullName; 
    @http:Field: {name: "phone-number" }
         string phoneNumber; 
}
resource isolated function get customer/groups(map<string|string[]> headers = {}, *GetClientQueries queries) returns KarbonApiContactsV2ClientGroupSummaryDTO|error {
       …
   }

# Represents the Queries record for the operation
public type GetClientQueries record {
    #query annotation for the parameter 
    @http:Query{ name: "customer-group" }
    string? customerGroup?;
    //other remaining query parameters
};

Here mentioned @http:Field is used for data binding with actual payload, the proposal can be found here. This annotation value will populate using the extensions we have mentioned in the above extension details section. This annotation allows users to define custom names for fields when they are serialized to OAS.
Mentioned @http:Query annotation is used to capture the query parameter name modification in client/service generation Annotation implementation more details can be found here : https://github.com/ballerina-platform/ballerina-library/issues/6747

ballerina-platform / ballerina-library