Client generation with required sanitization

[rahul1995]

Purpose

To create the OpenAPI spec, sanitize it to make compatible with Ballerina OpenAPI tool, and generate Client using it.

Issue Title: Introduce a Ballerina connector for Dropbox REST API
Issue link: ballerina-platform/ballerina-library#7054

Examples

Checklist

• Linked to an issue
• Updated the changelog
• Added tests
• Updated the spec
• Checked native-image compatibility

[lnash94]

@rahul1995, This generated OpenAPI looks good 😃, Here I have noticed a few improvements we can add.

• Given that the OpenAPI specification has a lot of inline schemas for particular request bodies and responses, shall we move them to named schemas under the components section, define names that properly align with Ballerina record naming best practices, and refer to them in the relevant places?

ex: some sample for the inline schema

"requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "photo": {
                    "type": "object",
                    "properties": {
                      ".tag": {
                        "type": "string",
                        "example": "base64_data"
                      },
                      "base64_data": {
                        "type": "string",
                        "example": "SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4="
                      }
                    }
                  }
                }
              },

After modified ,
the inline schema need to be sent under the component.schemas section with named object and reference it into relevant requestBody or response in operation.

"component": {
          "schemas": {
            "ProfilePhoto": {
              "schema": {
                "type": "object",
                "properties": {
                  "photo": {
                    "type": "object",
                    "properties": {
                      ".tag": {
                        "type": "string",
                        "example": "base64_data"
                      },
                      "base64_data": {
                        "type": "string",
                        "example": "SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4="
                      }
                    }
                  }
                }
              },
...
"requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/component/schemas/ProfilePhoto"
                    }
                  }
                }
              },

[rahul1995]

@lnash94 Thanks for the review. I agree with your comment, but this is like 35k lines of json file. It's looking infeasible for me to finish it as an individual. Can I improve some main API endpoints for now and take this as a task for later (distributed among other folks if possible)?

[lnash94]

@lnash94 Thanks for the review. I agree with your comment, but this is like 35k lines of json file. It's looking infeasible for me to finish it as an individual. Can I improve some main API endpoints for now and take this as a task for later (distributed among other folks if possible)?

Hi @rahul1995,

Yeah, it is understandable that this has a lot of endpoints. Until we provide the set of operations, I can bring some workarounds to you to address the pain points here.
Workaround:

1. Instead of the JSON format, let's use YAML format to increase readability and reduce unnecessary line counts. You can use this Swagger editor: https://editor-next.swagger.io/ to convert it into YAML format.
2. Then, you can use the same editor to generate a server or client using OpenAPI as the language. It will generate the YAML and automatically move inline objects into named records (you can use any preferred method here).
3. Once you receive the YAML, you can edit the name references by giving them meaningful names that align with Ballerina best practices. ex: inline_response_200_73_event_category -> EventCategoryResponse

Please Note: during every modification lets check the modified details in the API is align with the original API documentation 😊.
Hope this workaround helps alleviate the issues you're experiencing. If you have any questions or need additional assistance, please don't hesitate to reach out to us. We're here to help 🙌 !

[rahul1995]

@lnash94 Thanks for sharing this method. It will save a lot of time.
I see that there are ~500 named schemas which I need to rename because many names are like inline_response_xxx, and others are not following the best practices.

Since these many will take a while, I have created a commit with a few renamed so that I get an early review on this.
Could you please review?

[lnash94]

@lnash94 Thanks for sharing this method. It will save a lot of time. I see that there are ~500 named schemas which I need to rename because many names are like inline_response_xxx, and others are not following the best practices.

Since these many will take a while, I have created a commit with a few renamed so that I get an early review on this. Could you please review?

Yeah sure , I will review :)

[lnash94]

@rahul1995, avoiding using verbs as prefixes in record names is generally recommended. The best practice is to focus on the state or data the record represents rather than the action performed on it.

Shall we simplify the object name by minimizing the action verb for clarity and alignment with Ballerina's name?

ex: AddPropertiesRequest -> NewPropertiesRequest, PropertiesRequest

Please check and apply this to other relevant places.

[rahul1995]

@lnash94 I have made it like this only, it is that sometimes a particular API endpoint requires a specific format of request, that is where I am also creating records specific to that request body and naming it with verb. For example, I first created a record/schema Photo and then I created SetProfilePhotoRequest using Photo schema to define the format SetProfilePhoto API expects.

I have used the same practices as done in https://github.com/ballerina-platform/module-ballerinax-twitter/blob/main/docs/spec/openapi.json

[rahul1995]

Hey @lnash94 thanks for the review :) I cleaned up a little bit and added PRs for tests, examples, and documentations.

For the Schema naming, the current strategy is also in line with the Dropbox's official documentation, i.e. Dropbox also uses same naming conventions (verb + API Name + Arg/Result). For example, AddTemplateResult as shown in the screenshot attached for the /templates/add_for_user API.

Please let me know how we should proceed further. 😊

[lnash94]

Hi @rahul1995

Hey @lnash94 thanks for the review :) I cleaned up a little bit and added PRs for tests, examples, and documentations.

For the Schema naming, the current strategy is also in line with the Dropbox's official documentation, i.e. Dropbox also uses same naming conventions (verb + API Name + Arg/Result). For example, AddTemplateResult as shown in the screenshot attached for the /templates/add_for_user API.

Please let me know how we should proceed further. 😊

Let's proceed with the process (verb + API Name + Arg/Result) , it is fine :) . lets follow the same thing which has been done in Dropbox.

[rahul1995]

Thanks @lnash94. I have exactly matched these names as given in the documentation. Please review.

Also, I am open to contribute further outside of Hacktoberfest if needed :)
Learned a lot about OpenAPI during this task.

[NipunaRanasinghe]

LGTM