docs: rework the new client section and small guide on pre-releases (#4800)

Author: shortcuts

generators/src/main/java/com/algolia/codegen/utils/Helpers.java

@@ -175,20 +175,20 @@ public static void removeHelpers(OperationsMap operations) {
   /**
    * Get the current version of the given client from the
    * `clients/algoliasearch-client-javascript/packages/${client}/package.json` file, defaults to
-   * 0.0.1 if not found
+   * 0.0.1-alpha.0 if not found
    */
   public static String getPackageJsonVersion(String client) throws ConfigException {
     try {
       JsonNode packageJson = Helpers.readJsonFile("clients/algoliasearch-client-javascript/packages/" + client + "/package.json");
       String value = packageJson.get("version").asText();
 
       if (value.isEmpty()) {
-        return "0.0.1";
+        return "0.0.1-alpha.0";
       }
 
       return value;
     } catch (ConfigException e) {
-      return "0.0.1";
+      return "0.0.1-alpha.0";
     }
   }
 

website/docs/docs.md renamed to website/docs/add-a-new-api/api-documentation-guidelines.md

@@ -1,5 +1,5 @@
 ---
-title: API documentation
+title: API documentation guidelines
 description: Guidelines for writing API documentation for Algolia's APIs.
 ---
 
@@ -14,7 +14,7 @@ For more general documentation guidelines,
 see the [Google developer documentation style guide](https://developers.google.com/style).
 
 For information on how to structure spec files to support a new API client,
-see [Add a new API client](./add-new-api-client.md).
+see [Add a new API client](/docs/add-a-new-language).
 
 ## Prefer plain text
 

website/docs/add-a-new-api/generate-your-client.md

@@ -0,0 +1,57 @@
+---
+title: Generate your client
+---
+
+:::info
+
+Make sure to first read the [setup the repository tooling section](/docs/setup-repository) first.
+
+This section is only about **adding to the existing API clients**, to support a new programming language, see [Support a new language](/docs/add-a-new-language).
+
+:::
+
+## Configuration file
+
+> Most of the configuration is determined by the api-clients-automation CLI (`scripts/`).
+
+The file [`config/clients.config.json`](https://github.com/algolia/api-clients-automation/blob/main/config/clients.config.json) contains information that's common to all clients generated for each language, you can [find its JSON schema here](https://github.com/algolia/api-clients-automation/blob/main/config/clients.schema.json).
+
+## CLI Commands
+
+Use the CLI to generate your client:
+
+- [Commands for working with clients](/docs/CLI/generate-commands)
+
+## Generate a pre-release client
+
+:::info
+
+Only the JavaScript client releases standalone packages along with the main `algoliasearch` package, so it's the only possible "generated" solution for pre-releases (alpha or beta).
+
+:::
+
+1. [Update the configuration file](https://github.com/algolia/api-clients-automation/blob/main/config/clients.config.json#L131)
+
+The `clients` field define which specification to generate and their output location. In order to create a pre-release for your API, it needs to be standalone only (non bundled with `algoliasearch`).
+
+```json
+{
+  "name": "awesomeapi", // this must match the name of the specification
+  "output": "clients/algoliasearch-client-javascript/packages/awesomeapi", // make sure to keep everything in `clients/algoliasearch-client-javascript/packages/`
+  "isStandaloneClient": true // this tells the generator not to put it in the `algoliasearch` bundle
+},
+```
+
+2. Generate your client
+
+With just the above changes, you can now run `yarn cli generate -h` which should output a complete list of the available APIs for Javascript, `awesomeapi` should be in it.
+
+Running `yarn cli generate javascript awesomeapi` will generate the client and format it, and `yarn cli build clients javascript awesomeapi` will bundle it.
+
+3. Test the client
+
+At least one test per operation is required, you can read more about it in the [Common Test Suite section](/docs/testing/common-test-suite.md).
+
+4. Release
+
+We take care of it, open your pull request :)

website/docs/add-a-new-api/write-a-specification.md

@@ -0,0 +1,135 @@
+---
+title: Write an OpenAPI specification
+---
+
+:::info
+
+Algolia's API specs follow the [OpenAPI specification, version 3.1](https://spec.openapis.org/oas/v3.1.0).
+
+Starting from an existing specification **really eases the contribution process and is recommended** (e.g. [search](https://github.com/algolia/api-clients-automation/blob/main/specs/search/))
+
+**Do not edit the files in [`specs/bundled`](https://github.com/algolia/api-clients-automation/blob/main/specs/bundled)** they are the generated from the manually written specifications, and only used to generate API clients.
+
+:::
+
+:::caution
+
+A specification is used to generate the API client, its tests and code snippets, but is most importantly served by [the Algolia public documentation](https://www.algolia.com/doc/api-reference/rest-api/), please read our [API Documentation guidelines](./api-documentation-guidelines.md) to properly document your specification.
+
+:::
+
+# Structure your specification
+
+Each API specification follows a consistent structure.
+
+## `specs/common/`
+
+This [common directory](https://github.com/algolia/api-clients-automation/blob/main/specs/common/) contains schemas and parameters that are common to multiple Algolia APIs, for example: search parameters or indexName definitions.
+
+## `specs/<apiName>/`
+
+Each API must be contained in its own directory, for example: [the Search API](https://github.com/algolia/api-clients-automation/blob/main/specs/search/).
+
+### `specs/<apiName>/spec.yml`
+
+This file is the main entrypoint of your specification and should describe your API, including the `servers`, `securitySchemes` and `paths` properties.
+
+### `specs/<apiName>/common/`
+
+This directory contains schemas and parameters that are common to **your API**.
+For schemas that are shared between multiple APIs please use the global [`specs/common`](#specscommon) directory.
+
+### `specs/<apiName>/paths/`
+
+This directory contains the descriptions of the **endpoints** of your API.
+The paths themselves are defined in the [`spec.yml`](#specsapinamespecyml) file.
+
+#### `specs/<apiName>/paths/<operation>.yml`
+
+Operations are endpoints combined with an HTTP method (`GET`, `POST`, etc.).
+Each operation must have a unique `operationID` property.
+Operations for the same endpoint may share the same file, for example, the `GET` and `DELETE` request for the same endpoint.
+
+##### Filenames
+
+Follow these conventions:
+
+- If the file only contains one operation, use `<operationId>.yml` as filename.
+- If the file contains multiple operations, use a more generic name, for example [`rule.yml`](https://github.com/algolia/api-clients-automation/blob/main/specs/search/paths/rules/rule.yml) for the `GET`, `PUT`, and `DELETE` request for a rule.
+
+##### Summaries and descriptions
+
+Every operation must have a `summary` and `description` property (they will be used in the generated API clients, and the Algolia documentation).
+For information about documenting operations, see [Operation summaries](/docs/add-a-new-api/api-documentation-guidelines#operation-summaries) and [Operation descriptions](./api-documentation-guidelines.md#operation-descriptions).
+
+##### Access Control Lists (ACL)
+
+Each operation should include an `x-acl` property
+to document the ACL required to make the request.
+
+The `x-acl` property is an array of strings, the allowed values are: `search`, `browse`, `addObject`, `deleteObject`, `listIndexes`, `deleteIndex`, `settings`, `editSettings`, `analytics`, `recommendation`, `usage`, `logs`, `setUnretrievableAttributes`, `admin`.
+For operations that require the admin API key, use `admin`
+
+##### Complex objects
+
+The following objects must not be inlined, but referenced with `$ref`:
+
+- Nested arrays
+- Nested objects
+- `oneOf`
+- `allOf`
+- `enum`
+
+This is required for accurate naming of the generated code objects.
+It also improves the readability of the specs.
+
+##### Properties and parameters
+
+- Create separate objects and reference them for [complex objects](#complex-objects).
+- The `format` parameter for strings isn't supported.
+- For **nullable properties**, use the following syntax:
+
+  ```yaml
+  nullableProp:
+    default: null
+    oneOf:
+      - type: string
+        description: Some value
+      - type: 'null'
+        description: The single quotes are required.
+  ```
+
+For information about documenting properties and parameters, see [Properties and parameters](/docs/add-a-new-api/api-documentation-guidelines#properties-and-parameter-descriptions).
+
+## CLI Commands
+
+Use the CLI to generate build your specs:
+
+- [Commands for working with specs](/docs/CLI/build-commands)
+
+## Troubleshooting
+
+### Explicit names for request bodies
+
+> [Detailed issue](https://github.com/algolia/api-clients-automation/issues/891)
+
+In some cases, the generated name for the `requestBody` property might be wrong.
+This can happen in these cases:
+
+- The type is too complex or too broad to be correctly generated,
+  for example, [an object with `additionalProperties`](https://github.com/algolia/api-clients-automation/tree/main/specs/search/paths/objects/partialUpdate.yml#L24-L33).
+
+- The type is an alias of its model,
+  for example, [a list of `model`](https://github.com/algolia/api-clients-automation/tree/main/specs/search/paths/rules/saveRules.yml#L12-L20).
+
+To provide a name for the request body, add the [`x-codegen-request-body-name`](https://openapi-generator.tech/docs/swagger-codegen-migration/#body-parameter-name) property to the root of the operation's spec file.
+
+For an example, see [pull request #896](https://github.com/algolia/api-clients-automation/pull/896).
+
+### Send additional options to the templates
+
+To send additional information to the generators,
+you can add properties starting with `x-` to the root level of your spec.
+These are available in the templates as part of the `vendorExtensions` object.
+
+For an example, see [`search.yml`](https://github.com/algolia/api-clients-automation/blob/main/specs/search/paths/search/search.yml#L5-L7)

website/docs/add-new-language.md renamed to website/docs/add-a-new-language.md

@@ -1,5 +1,5 @@
 ---
-title: Support a new language
+title: Add a new language
 ---
 
 :::info
@@ -28,10 +28,6 @@ Example for the `JavaScript` client with the `typescript-node` template:
 apic exec java "yarn openapi-generator-cli author template -g typescript-node -o templates/javascript/"
 ```
 
-## Update the generator config
-
-Please read the [`add a new client guide`](/docs/add-new-api-client) for information on how to structure your new client and setup the configuration files.
-
 ### Algolia requirements
 
 :::caution
@@ -71,8 +67,6 @@ The retry strategy cannot be generated and needs to be implemented outside of th
 
 Some Algolia clients (search and recommend) targets the default appId host (`${appId}-dsn.algolia.net`, `${appId}.algolia.net`, etc.), while clients like `personalization` have their own regional `host` (`eu` | `us` | `de`).
 
-As the generator does not support reading `servers` in a spec file **yet**, hosts methods and variables are extracted with a custom script and create variables for you to use in the mustache templates, [read more here](/docs/add-new-api-client#2-configure-the-generator).
-
 ### User Agent
 
 The header 'User-Agent' must respect a strict pattern of a base, client, plus additional user defined segments: