docs: add troubleshooting section to contributing guide

Author: shortcuts

website/docs/contributing/add-new-api-client.md

@@ -2,54 +2,78 @@
 title: Add a new API client
 ---
 
-# Add a new API client
-
-Adding an API client requires manual steps in order to setup the tooling, generation scripts and properly generate the code. We recommend getting inspirations from existing clients such as `javascript-recommend`.
-
 :::info
 
 Make sure to first [setup the repository tooling](/docs/contributing/setup-repository) to ease your journey!
 
 :::
 
+# Add a new API client
+
+Adding a new API client requires some manual steps in order to have a properly working client:
+
+1. [Writing specs](#1-writing-specs)
+2. [Configuring the generator](#2-configuring-the-generator)
+3. [Generate the client](#3-generate-the-client)
+4. [Adding tests](#4-adding-tests-with-the-common-test-suite)
+
 ## 1. Writing specs
 
-We recommend to have a look at [existing spec files](https://github.com/algolia/api-clients-automation/blob/main/specs/). The `bundled` folder is automatically generated, manual changes shouldn't be done in these files.
+We recommend to have a look at [existing spec files](https://github.com/algolia/api-clients-automation/blob/main/specs/).
+
+> **The `bundled` folder is automatically generated, manual changes shouldn't be done in these files.**
+
+### Guidelines
+
+- **Endpoints**: Each file in [the `paths` folder](https://github.com/algolia/api-clients-automation/tree/main/specs/search/paths) should contain `operationId`s for a single endpoint, multiple methods are allowed.
+- **File name**:
+  - When the `path` file only contain one method (e.g. `GET`), we name the file after the `operationId`
+  - When multiple methods are present (e.g. `PUT` and `DELETE`), we pick a more generic name that is related to the endpoint itself.
+- **Description/Summary**: `operationId`s must have both description and summary.
+- **Complex objects**: Complex objects (nested arrays, nested objects, `oneOf`, `allOf`, etc.) must be referenced (`$ref`) in the `operationId` file and not inlined. This is required to provide a accurate naming and improve readability.
 
 ### `common` spec folder
 
-[This folder](https://github.com/algolia/api-clients-automation/blob/main/specs/common/) hosts properties that are common to Algolia or used in multiple clients.
+[The `common` folder](https://github.com/algolia/api-clients-automation/blob/main/specs/common/) hosts properties that are common to Algolia and/or used in multiple clients.
 
 ### `<clientName>` spec folder
 
 > Example with the [search client spec](https://github.com/algolia/api-clients-automation/blob/main/specs/search/)
 
 #### `spec.yml` file
 
-This file is the entry point of the client spec, it contains `servers`, `paths` and other specific information of the API. We recommend to copy an existing [`spec.yml` file](https://github.com/algolia/api-clients-automation/blob/main/specs/search/spec.yml) to get started.
+The `spec.yml` file is the entry point of the client spec, it contains `servers`, `paths` and other specific information of the API. We recommend to copy an existing [`spec.yml` file](https://github.com/algolia/api-clients-automation/blob/main/specs/search/spec.yml) to get started.
 
 #### `<clientName>`/common folder
 
-Properties that are common to the client, for properties common to all clients, check the [common folder](#common-spec-folder).
+Same as [the `common` folder](#common-spec-folder) but only related to the current client.
 
 #### `<clientName>`/paths folder
 
-Path definition of the paths defined in the [spec file](#specyml-file).
+Path definition of the paths defined in the [spec file](#specyml-file). See [guidelines](#guidelines).
 
-### Send additional options to the template
+### Troubleshooting
 
-You might want to send additional information to the generators that have no link with your REST API. To do so, you can add parameters starting with `x-` at the root level of your spec, which will be available in the mustache template under the `vendorExtensions` object.
+#### Force the name of a `requestBody`
 
-[Example in the `search.yml` spec](https://github.com/algolia/api-clients-automation/blob/main/specs/search/paths/search/search.yml#L5) and how it is used [in a mustache file](https://github.com/algolia/api-clients-automation/blob/bf4271246f9282d3c11dd46918e74cb86d9c96dc/templates/java/libraries/okhttp-gson/api.mustache#L196).
+> [Detailed issue](https://github.com/algolia/api-clients-automation/issues/891)
 
-#### Guidelines
+In some cases, you can encounter wrongly named `requestBody` from the specs, which is due to:
 
-- **Endpoints**: Each file in the `paths` folder should contain `operationId`s for a single endpoint, but multiple methods are allowed.
-- **Name**: If the path file only contain one method, we name the file same as the `operationId`, but we try to make it less specific if there is multiple methods.
-- **Description/Summary**: `operationId`s must have both description and summary.
-- **Complex objects**: Complex objects (nested arrays, nested objects, , `oneOf`, `allOf`, etc.) must be referenced (`$ref`) in the `operationId` file and not inlined. This is required to provide a accurate naming and improve readability.
+- The type is too complex/too broad to be generated. (e.g. [An object with `additionalProperties`](https://github.com/algolia/api-clients-automation/tree/main/specs/search/paths/objects/partialUpdate.yml#L24-L33))
+- The body is an alias of its sub type (e.g. [A list of sub models](https://github.com/algolia/api-clients-automation/tree/main/specs/search/paths/rules/saveRules.yml#L12-L20))
+
+The `x-codegen-request-body-name` property can be added at the root of the spec, to force the name of the generated `requestBody` property.
+
+You can find an example of this implementation [on this PR](https://github.com/algolia/api-clients-automation/pull/896).
+
+#### Send additional options to the template
+
+You might want to send additional information to the generators. To do so, you can add parameters starting with an `x-` at the root level of your spec, which will be available in the `mustache` template under the `vendorExtensions` object.
+
+[Example in the `search.yml` spec](https://github.com/algolia/api-clients-automation/blob/main/specs/search/paths/search/search.yml#L5-L7) and how it is used [in a mustache file](https://github.com/algolia/api-clients-automation/blob/bf4271246f9282d3c11dd46918e74cb86d9c96dc/templates/java/libraries/okhttp-gson/api.mustache#L196).
 
-## 2. Configuring the environment
+## 2. Configuring the generator
 
 > The generator follows its own configuration file named `config/openapitools.json`
 
@@ -75,10 +99,10 @@ Below are the options you need to **make sure to define for your client**, other
 | `apiFolder`           | `clients.config.json` |           All           | The path to the `api` folder that will host the generated code.                                                      |
 | `customGenerator`     | `clients.config.json` |           All           | The name of the generator used to generate code.                                                                     |
 
-## 3. Generate new client
+## 3. Generate the client
 
 You can find all the commands in the [CLI > clients commands page](/docs/contributing/CLI/clients-commands) and [CLI > specs commands page](/docs/contributing/CLI/specs-commands).
 
-## 4. Implementing the Common Test Suite
+## 4. Adding tests with the Common Test Suite
 
 Clients needs to be tested, you can read more in the [Common Test Suite](/docs/contributing/testing/common-test-suite) guide.