diff --git a/website/docs/clients/guides/filtering-your-search.mdx b/website/docs/clients/guides/filtering-your-search.mdx index eaa7e75bd3..dc25a6c624 100644 --- a/website/docs/clients/guides/filtering-your-search.mdx +++ b/website/docs/clients/guides/filtering-your-search.mdx @@ -15,13 +15,13 @@ Initially, filter attributes must be defined as facets, using the `attributesFor - + ```js await client.setSettings({ @@ -57,13 +57,13 @@ The actual filtering of records is performed at query time, not at indexing time - + ```js // Only "Scarlett Johansson" actor @@ -145,13 +145,13 @@ $client->search([ - + ```js // Only "Scarlett Johansson" actor diff --git a/website/docs/clients/guides/retrieving-facets.mdx b/website/docs/clients/guides/retrieving-facets.mdx index d10ea8a4c7..9fbf28922d 100644 --- a/website/docs/clients/guides/retrieving-facets.mdx +++ b/website/docs/clients/guides/retrieving-facets.mdx @@ -13,13 +13,13 @@ For example, you can retrieve your books' facets with the `search` method, and t - + ```js await client.search({ diff --git a/website/docs/clients/guides/send-data-to-algolia.mdx b/website/docs/clients/guides/send-data-to-algolia.mdx index a4eaec2def..7ea5747630 100644 --- a/website/docs/clients/guides/send-data-to-algolia.mdx +++ b/website/docs/clients/guides/send-data-to-algolia.mdx @@ -19,13 +19,13 @@ To push data to Algolia, you need an Application ID and a valid API key with the - + ```js // for the default version @@ -57,13 +57,13 @@ Before sending anything to Algolia, you need to retrieve your data. You can do t - + ```js const records = [{ name: 'Tom Cruise' }, { name: 'Scarlett Johansson' }]; diff --git a/website/docs/clients/migration-guide.mdx b/website/docs/clients/migration-guide.mdx index b79b1b0032..1d8ac05ef1 100644 --- a/website/docs/clients/migration-guide.mdx +++ b/website/docs/clients/migration-guide.mdx @@ -23,20 +23,18 @@ The changes below are effective on all of the API clients. | ----------- | :---------- | :------------------------------------------------------------------------------------------------------ | | `initIndex` | **removed** | All methods are now available at the client level. [See example below](#methods-targeting-an-indexname) | -## API Client specific breaking changes +## Client's specific breaking changes -The changes below are effective on the selected API client. - -For informations regarding the installation of the package, please see [the installation page](/docs/clients/installation) +The changes below are effective on the selected API client. For information regarding the installation of the package, please see [the installation page](/docs/clients/installation). - + | Previous | Latest | Impacted clients | Description | | -------------------- | :------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -47,7 +45,7 @@ For informations regarding the installation of the package, please see [the inst -### Installation +### Usage - + + +| Previous | Latest | Impacted clients | Description | +| -------------------- | :------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@algolia` | `@experimental-api-clients-automation` | JavaScript | **During the beta phase**, the clients are available under the NPM `@experimental-api-clients-automation` namespace, you can find a full list [here](https://www.npmjs.com/org/experimental-api-clients-automation). | +| `algoliasearch/lite` | `algoliasearch-lite` | JavaScript | The lite version of the client now have [its own package](https://www.npmjs.com/package/@experimental-api-clients-automation/algoliasearch-lite). | +| `search` | `searchClient` | all | Exported clients are suffixed by `Client`. | To get started, first install the `algoliasearch` client. @@ -100,7 +104,7 @@ You can continue this guide on [our installation page](/docs/clients/installatio { label: 'JavaScript', value: 'javascript', } ] }> - + Prior to the `initIndex` removal stated in the [Common breaking changes](#common-breaking-changes), all methods previously available at the `initIndex` level requires the `indexName` to be sent with the query. diff --git a/website/docs/contributing/CLI/clients-commands.md b/website/docs/contributing/CLI/clients-commands.md index 02fcbb09e6..f3ec06088a 100644 --- a/website/docs/contributing/CLI/clients-commands.md +++ b/website/docs/contributing/CLI/clients-commands.md @@ -10,8 +10,10 @@ The Clients commands are used to [`generate`](#generate) and [`build`](#build) A > `language` and `client` defaults to `all` +> The `client` parameter is variadic, you can pass multiple `client` name + ```bash -yarn docker generate +yarn docker generate ``` ### Available options @@ -35,6 +37,12 @@ yarn docker generate yarn docker generate java sources ``` +### Generate many client for specific language + +```bash +yarn docker generate php sources recommend search +``` + ## Build ### Build all clients for all supported languages @@ -48,3 +56,9 @@ yarn docker build clients ```bash yarn docker build clients javascript recommend ``` + +### Build many client for specific language + +```bash +yarn docker build clients php sources recommend search +``` diff --git a/website/docs/contributing/CLI/cts-commands.md b/website/docs/contributing/CLI/cts-commands.md index 55eadb0ba1..be8a6056ac 100644 --- a/website/docs/contributing/CLI/cts-commands.md +++ b/website/docs/contributing/CLI/cts-commands.md @@ -16,8 +16,10 @@ The Common Test Suite commands are used to [`generate`](#generate) and [`run`](# > `language` and `client` defaults to `all` +> The `client` parameter is variadic, you can pass multiple `client` name + ```bash -yarn docker cts generate +yarn docker cts generate ``` ### Available options @@ -41,6 +43,12 @@ yarn docker cts generate yarn docker cts generate java sources ``` +### Generate CTS for many client for specific language + +```bash +yarn docker cts generate php sources recommend search +``` + ## Run ### Run CTS for all supported languages @@ -48,3 +56,9 @@ yarn docker cts generate java sources ```bash yarn docker cts run ``` + +### Run CTS for a specific languages + +```bash +yarn docker cts run javascript +``` diff --git a/website/docs/contributing/CLI/specs-commands.md b/website/docs/contributing/CLI/specs-commands.md index 1c6c60831b..b453f8475b 100644 --- a/website/docs/contributing/CLI/specs-commands.md +++ b/website/docs/contributing/CLI/specs-commands.md @@ -10,8 +10,10 @@ The Specs commands are used to [`build`](#build), [`lint`](#lint) and validate t > `client` defaults to `all` +> The `client` parameter is variadic, you can pass multiple `client` name + ```bash -yarn docker build specs +yarn docker build specs ``` ### Available options @@ -36,6 +38,12 @@ yarn docker build specs yarn docker build specs recommend ``` +### Build many spec + +```bash +yarn docker build specs recommend search predict +``` + ## Lint ### Fix specs diff --git a/website/docs/contributing/add-new-api-client.md b/website/docs/contributing/add-new-api-client.md index a01f3a64e7..98bf9b7188 100644 --- a/website/docs/contributing/add-new-api-client.md +++ b/website/docs/contributing/add-new-api-client.md @@ -4,7 +4,7 @@ title: Add a new API client # Add a new API client -Adding an API client requires a 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`. +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 @@ -26,22 +26,28 @@ We recommend to have a look at [existing spec files](https://github.com/algolia/ #### `spec.yml` file -This file is the entry point of the client spec, it contains `servers`, `paths` and other specific imformations 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. +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. #### ``/common folder -Properties that are common to the client, for properties common to all clients, check the [common folder](#common-spec-folder) +Properties that are common to the client, for properties common to all clients, check the [common folder](#common-spec-folder). #### ``/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). + +### Send extra options to the template + +You might want to send extra 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. + +[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). #### Guidelines - **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 `operantionId` file and not inlined. This is required to provide a accurate naming and improve readability. +- **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. ## 2. Configuring the environment @@ -49,50 +55,30 @@ Path definition of the paths defined in the [spec file](#specyml-file) ### Generation config -[config/openapitools.json](https://github.com/algolia/api-clients-automation/blob/main/config/openapitools.json) hosts the configuration of all of the generated clients with their available languages. +[`config/openapitools.json`](https://github.com/algolia/api-clients-automation/blob/main/config/openapitools.json) and [`config/clients.config.json`](https://github.com/algolia/api-clients-automation/blob/main/config/clients.config.json) hosts the configuration of all of the generated clients with their available languages and extra information. #### `generators` Generators are referenced by key with the following pattern `-`. You can copy an existing object of a client and replace the `` value with the one you'd like to generate. -Below are the options you need to **make sure to define for your client**, other options are automatically added in the [`setDefaultOptions` script](https://github.com/algolia/api-clients-automation/blob/main/scripts/pre-gen/setDefaultGeneratorOptions.ts) and the generators. - -| Option | Type | Language | Example | Definition | -| -------------- | :----: | :--------: | :-----------------------------: | :------------------------------------------------------------------------------------------------------------------- | -| output | string | Common | `path/to/client/client-sources` | The output path of the client. | -| gitRepoId | string | Common | `algoliasearch-client-java-2` | The name of the repository under the Algolia org. | -| packageName | string | common | `AlgoliaSearch` | Name of the API package, used in [CTS](/docs/contributing/testing/common-test-suite). | -| packageVersion | string | JavaScript | `1.2.3` | The version you'd like to publish the first iteration of the generated client. It will be automatically incremented. | - -### GitHub actions - -The built clients are cached with the [Cache GitHub Action](https://github.com/algolia/api-clients-automation/blob/main/.github/actions/cache/action.yml) to avoid unnecessary CI tasks. - -You can copy [an existing client caching step](https://github.com/algolia/api-clients-automation/blob/main/.github/actions/cache/action.yml) or edit the following example: - -```yaml -- name: Restore built client - if: ${{ inputs.job == 'cts' || inputs.job == 'codegen' }} - uses: actions/cache@v3 - with: - path: - key: | - ${{ env.CACHE_VERSION }}-${{ - hashFiles( - , - 'specs/bundled/.yml', - 'templates//**', - 'generators/src/**' - )}} -``` +Below are the options you need to **make sure to define for your client**, other options are automatically added by our generator. + +| Option | File | Language | Description | +| --------------------- | :-------------------: | :---------------------: | -------------------------------------------------------------------------------------------------------------------- | +| `output` | `openapitools.json` | All | The output path of the client. | +| `packageName` | `openapitools.json` | All | Name of the API package, used in [CTS](/docs/contributing/testing/common-test-suite). | +| `packageVersion` | `openapitools.json` | JavaScript | The version you'd like to publish the first iteration of the generated client. It will be automatically incremented. | +| `utilsPackageVersion` | `clients.config.json` | JavaScript | The version of the utils package. Every utils package should have synchronized version. | +| `packageVersion` | `clients.config.json` | All (except JavaScript) | The version you'd like to publish the first iteration of the generated client. It will be automatically incremented. | +| `gitRepoId` | `clients.config.json` | All | The name of the repository. | +| `folder` | `clients.config.json` | All | The path to the folder that will host the generated code. | +| `modelFolder` | `clients.config.json` | All | The path to the `model` folder that will host the generated code. | +| `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 -> 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). - -```bash -yarn docker generate -``` +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 diff --git a/website/docs/contributing/add-new-language.md b/website/docs/contributing/add-new-language.md index d636036fdd..070246fc87 100644 --- a/website/docs/contributing/add-new-language.md +++ b/website/docs/contributing/add-new-language.md @@ -34,9 +34,7 @@ openapi-generator author template -g typescript-node -o templates/javascript/ ## Update the generator config -Add each client in the file [`config/openapitools.json`](https://github.com/algolia/api-clients-automation/blob/main/config/openapitools.json), following the others client structure. - -> See [`add a new client`](/docs/contributing/add-new-api-client) for informations on how to structure your new client. +Please read the [`add a new client guide`](/docs/contributing/add-new-api-client) for information on how to structure your new client and setup the configuration files. ### Algolia requirements @@ -124,6 +122,20 @@ and that prevent us from upgrading our deps. In some languages it also requires To achieve this you can create interfaces that can be exposed, and wrap the method you want to be exposed, for an HTTP client for example. +### `useReadTransporter` + +Some methods of our REST API send `POST` requests via the `read` transporter of the API client, to reflect this implementation, we provide a variable in the template for you to distinguish those methods, called `vendorExtensions.x-use-read-transporter`. + +This option is provided [at the spec level](https://github.com/algolia/api-clients-automation/blob/main/specs/search/paths/search/search.yml#L5) and [used in the mustache files](https://github.com/algolia/api-clients-automation/blob/bf4271246f9282d3c11dd46918e74cb86d9c96dc/templates/javascript/api-single.mustache#L221-L223). + +You can take a look at the implementation over all clients, [in this pull request](https://github.com/algolia/api-clients-automation/pull/525). + +### `requestOptions` + +Every methods of every clients provide a parameter that does not exist in the REST API, called `requestOptions`. + +This parameter **must** be the last parameter of a method, and allow a user to override/merge extra `query parameters` or `headers` with the transporter ones. + ### Requesters > TODO: informations diff --git a/website/docs/contributing/testing/common-test-suite.md b/website/docs/contributing/testing/common-test-suite.md index 8f95e0a816..7b53415c61 100644 --- a/website/docs/contributing/testing/common-test-suite.md +++ b/website/docs/contributing/testing/common-test-suite.md @@ -5,7 +5,7 @@ title: Common Test Suite # Common Test Suite The CTS aims at ensuring minimal working operation for the API clients, by comparing the request formed by sample parameters. -It is automaticaly generated for all languages, from a JSON entry point. +It is automatically generated for all languages, from a JSON entry point. :::info @@ -24,24 +24,39 @@ The test generation script requires a JSON file name from the `operationId` (e.g ```json [ { - "testName": "the name of the test (e.g. test('search endpoint')) (default: 'method')", + "testName": "The name of the test (e.g. 'searches to testIndex with query parameters')", + // The parameters of you'd like to pass to the method "parameters": { "indexName": "testIndex", - "searchParam": { - // query parameters + "searchParams": { "offset": 42, "limit": 21, - // data parameters "query": "the string to search" }, - "otherParam": 22 + "facets": ["*"] }, + // Extra options sent with your method + "requestOptions": { + // Merged with transporter query parameters + "queryParameters": { + "anOtherParam": true + }, + // Merged with transporter headers + "headers": { + "x-header": "test" + } + }, + // The payload of the request "request": { "path": "/1/indexes/testIndex/query", "method": "POST", "body": { "query": "the string to search" }, "queryParameters": { - "otherParam": "22" + "otherParam": "22", + "anOtherParam": "true" + }, + "headers": { + "x-header": "test" } } } @@ -60,67 +75,111 @@ Create a template in [`tests/CTS/methods/requests/templates//reque When writing your template, here is a list of variables accessible from `mustache`: -```js +```json { "import": "the name of the package or library to import", "client": "the name of the API Client object to instanciate and import", - "blocks": [{ - // The list of test to implement - "operationID": "the name of the endpoint and the cts file to test", - "tests": [{ - "testName": "the descriptive name test (default to `method`)" - "method": "the method to call on the API Client", - "parameters": { - // Object of all parameters with their name, to be used for languages that require the parameter name - "parameterName": "value", - ... - }, - "parametersWithDataType": [ - { - "key": "key", - "value": "value", - // booleans indicating the data type - "isArray": false, - "isObject": true, - "isFreeFormObject": false, - "isString": false, - "isInteger": false, - "isLong": false, - "isDouble": false, - "isEnum": false, - "isBoolean": false, - "objectName": "SearchParams", - // oneOfModel empty if there is no oneOf - "oneOfModel": { - "parentClassName": "SearchParams", - "type": "SearchParamsObject" + "blocks": [ + { + // The list of test to implement + "operationID": "the name of the endpoint and the cts file to test", + "tests": [ + { + "testName": "the descriptive name test (default to `method`)", + "method": "the method to call on the API Client", + "parameters": { + // Object of all parameters with their name, to be used for languages that require the parameter name + "parameterName": "value" + // ... + }, + "parametersWithDataType": [ + { + "key": "key", + "value": "value", + // booleans indicating the data type + "isArray": false, + "isObject": true, + "isFreeFormObject": false, + "isString": false, + "isInteger": false, + "isLong": false, + "isDouble": false, + "isEnum": false, + "isBoolean": false, + "objectName": "SearchParams", + // oneOfModel empty if there is no oneOf + "oneOfModel": { + "parentClassName": "SearchParams", + "type": "SearchParamsObject" + }, + // properties used to have unique name and link to parent + "parent": "theParentObject", + "suffix": 7, + "parentSuffix": 6, + // boolean indicating if it is the last parameter + "-last": false + } + ], + "requestOptionsWithDataType": [ + { + "key": "key", + "value": "value", + // booleans indicating the data type + "isArray": false, + "isObject": true, + "isFreeFormObject": false, + "isString": false, + "isInteger": false, + "isLong": false, + "isDouble": false, + "isEnum": false, + "isBoolean": false, + "objectName": "SearchParams", + // oneOfModel empty if there is no oneOf + "oneOfModel": { + "parentClassName": "SearchParams", + "type": "SearchParamsObject" + }, + // properties used to have unique name and link to parent + "parent": "theParentObject", + "suffix": 7, + "parentSuffix": 6, + // boolean indicating if it is the last parameter + "-last": false + } + ], + // boolean indicating if the method has parameters, useful for `GET` requests + "hasParameters": true, + // boolean indicating if the method has requestOptions, useful to shape your template only if provided + "hasRequestOptions": true, + "request": { + "path": "the expected path of the request", + "method": "the expected method: GET, POST, PUT, DELETE or PATCH", + "body": { + // The expected body of the request }, - // properties used to have unique name and link to parent - "parent": "theParentObject", - "suffix": 7, - "parentSuffix": 6, - // boolean indicating if it is the last parameter - "-last": false, + "queryParameters": { + // key: string map + "parameterName": "stringify version of the value" + }, + "headers": { + // key: string map + "headerName": "stringify version of the value" + } } - ], - // boolean indicating if the method has parameters, useful for `GET` requests - "hasParameters": true, - "request": { - "path": "the expected path of the request", - "method": "the expected method: GET, POST, PUT, DELETE or PATCH", - "body": { - // The expected body of the request - } - "queryParameters": { - // key: string map - "parameterName": "stringify version of the value" } - } - }] - }] + ] + } + ] } ``` +## Add common tests to every clients + +You might want to test how every clients behaves, without having to duplicate the same tests. We provide 4 methods on every clients, common to all languages. + +You can find [the common folder](https://github.com/algolia/api-clients-automation/tree/main/tests/CTS/methods/requests/common) in the CTS too. [Adding a test](#how-to-add-test) in this folder will generate tests for all the clients. + ## Get the list of remaining CTS to implement To get the list of `operationId` not yet in the CTS but in the spec, run this command: