Skip to content

Commit

Permalink
docs: add recent changes to our contribution guides (#544)
Browse files Browse the repository at this point in the history
  • Loading branch information
@shortcuts
shortcuts authored May 25, 2022
1 parent 8aa4649 commit 1deea5f
Show file tree
Hide file tree
Showing 10 changed files with 231 additions and 134 deletions.
18 changes: 9 additions & 9 deletions website/docs/clients/guides/filtering-your-search.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ Initially, filter attributes must be defined as facets, using the `attributesFor

<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'JavaScript', value: 'javascript', },
{ label: 'PHP', value: 'php', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

```js
await client.setSettings({
Expand Down Expand Up @@ -57,13 +57,13 @@ The actual filtering of records is performed at query time, not at indexing time

<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'JavaScript', value: 'javascript', },
{ label: 'PHP', value: 'php', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

```js
// Only "Scarlett Johansson" actor
Expand Down Expand Up @@ -145,13 +145,13 @@ $client->search([

<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'JavaScript', value: 'javascript', },
{ label: 'PHP', value: 'php', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

```js
// Only "Scarlett Johansson" actor
Expand Down
6 changes: 3 additions & 3 deletions website/docs/clients/guides/retrieving-facets.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ For example, you can retrieve your books' facets with the `search` method, and t
<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'JavaScript', value: 'javascript', },
{ label: 'PHP', value: 'php', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

```js
await client.search({
Expand Down
12 changes: 6 additions & 6 deletions website/docs/clients/guides/send-data-to-algolia.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@ To push data to Algolia, you need an Application ID and a valid API key with the
<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'JavaScript', value: 'javascript', },
{ label: 'PHP', value: 'php', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

```js
// for the default version
Expand Down Expand Up @@ -57,13 +57,13 @@ Before sending anything to Algolia, you need to retrieve your data. You can do t

<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'JavaScript', value: 'javascript', },
{ label: 'PHP', value: 'php', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

```js
const records = [{ name: 'Tom Cruise' }, { name: 'Scarlett Johansson' }];
Expand Down
24 changes: 14 additions & 10 deletions website/docs/clients/migration-guide.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<Tabs
groupId="language"
defaultValue="js"
defaultValue="javascript"
values={[
{ label: 'JavaScript', value: 'js', }
{ label: 'JavaScript', value: 'javascript', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

| Previous | Latest | Impacted clients | Description |
| -------------------- | :------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -47,7 +45,7 @@ For informations regarding the installation of the package, please see [the inst
</TabItem>
</Tabs>

### Installation
### Usage

<Tabs
groupId="language"
Expand All @@ -56,7 +54,13 @@ For informations regarding the installation of the package, please see [the inst
{ label: 'JavaScript', value: 'javascript', }
]
}>
<TabItem value="js">
<TabItem value="javascript">

| 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.

Expand Down Expand Up @@ -100,7 +104,7 @@ You can continue this guide on [our installation page](/docs/clients/installatio
{ label: 'JavaScript', value: 'javascript', }
]
}>
<TabItem value="js">
<TabItem 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.

Expand Down
16 changes: 15 additions & 1 deletion website/docs/contributing/CLI/clients-commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <language | all> <client | all>
yarn docker generate <language | all> <client... | all>
```

### Available options
Expand All @@ -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
Expand All @@ -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
```
16 changes: 15 additions & 1 deletion website/docs/contributing/CLI/cts-commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <language | all> <client | all>
yarn docker cts generate <language | all> <client... | all>
```

### Available options
Expand All @@ -41,10 +43,22 @@ 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

```bash
yarn docker cts run
```

### Run CTS for a specific languages

```bash
yarn docker cts run javascript
```
10 changes: 9 additions & 1 deletion website/docs/contributing/CLI/specs-commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <client | all>
yarn docker build specs <client... | all>
```

### Available options
Expand All @@ -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
Expand Down
68 changes: 27 additions & 41 deletions website/docs/contributing/add-new-api-client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -26,73 +26,59 @@ 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.

#### `<clientName>`/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).

#### `<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).

### 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

> The generator follows its own configuration file named `config/openapitools.json`
### 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 `<languageName>-<clientName>`. You can copy an existing object of a client and replace the `<clientName>` 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 <languageName> <clientName> client
if: ${{ inputs.job == 'cts' || inputs.job == 'codegen' }}
uses: actions/cache@v3
with:
path: <PATH_TO_CLIENT_FOLDER>
key: |
${{ env.CACHE_VERSION }}-${{
hashFiles(
<clientName_FILES>,
'specs/bundled/<clientName>.yml',
'templates/<languageName>/**',
'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 <languageName> <clientName>
```
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

Expand Down
18 changes: 15 additions & 3 deletions website/docs/contributing/add-new-language.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 1deea5f

Please sign in to comment.