LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 04:21:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: documentation for telemetry + contributing guide update (#1139)

Browse Source 
Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>
Co-authored-by: Ihor Karpiuk <ihor.karpiuk@redocly.com>
This commit is contained in:
Andrew Tatomyr
2023-06-26 21:26:19 +03:00
committed by GitHub
parent 0e46aef217
commit 0ce9cab59a
7 changed files with 148 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
.github/CONTRIBUTING.md vendored
View File

@@ -72,6 +72,38 @@ $ npm run benchmark
There are some other scripts available in the `scripts` section of the `package.json` file. There are some other scripts available in the `scripts` section of the `package.json` file.
## Local source code usage
### NPM linking
To test the local source code of the packages in other local applications, you can use npm linking. See the [docs](https://docs.npmjs.com/cli/v9/commands/npm-link).
### Local packing and installing
To test local changes as a package, you can use the following steps:
1. Optionally, bump the version of the packages ([see details](#version-updating)).
1. Run `npm run pack:prepare` in the repository's root. This generates **redocly-cli.tgz** and **openapi-core.tgz** files and makes some changes to **packages/cli/package.json** file.
1. Copy **redocly-cli.tgz** file to a destination folder and then run `npm install redocly-cli.tgz` there to install Redocly CLI. To install `openapi-core` do the same but with **openapi-core.tgz** file.
Don't forget to revert the changes to **package.json** files later.
## Version updating
Keep the same versions for both packages. To increase the version follow the steps below:
1. First bump the version in **packages/core/package.json**.
1. Run `npm install` in the repository root.
1. Run `npm run compile` in the repository root.
1. Bump the version in **packages/cli/package.json** and **package.json** (3 entries in total).
1. Run `npm install` in the repository root.
## Contribute documentation ## Contribute documentation
### Prose linting ### Prose linting
@@ -94,6 +126,53 @@ mlc docs/
It only checks links within the local docs (it can't check links to other docs sections that are present when we publish all products under https://redocly.com/docs), and doesn't currently check anchors, so take care when renaming pages or titles. It only checks links within the local docs (it can't check links to other docs sections that are present when we publish all products under https://redocly.com/docs), and doesn't currently check anchors, so take care when renaming pages or titles.
### Built-in rules changes
After adding a new rule, make sure it is added to the `minimal`, `recommended` and `all` rulesets with appropriate severity levels. The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
Also add the rule to the `builtInRulesList` in [the config types tree](../packages/core/src/types/redocly-yaml.ts).
Separately, open a merge request with the corresponding documentation changes.
## Arguments usage
There are three ways of providing arguments to the CLI: environment variables, command line arguments, and Redocly configuration file.
### Environment variables
Environment variables should be used to provide some arguments that are common for all the commands.
We always prefer configuration over environment variables.
Environment variables should not affect the **core** package logic.
### Command line arguments
Use them to provide some arguments that are specific to a certain command. Think of them as modifiers. They should not affect the **core** package logic.
### Configuration file
The **redocly.yaml** file is the most flexible way of providing arguments. Please use it to provide arguments that are common for all the commands, for a specific command, or for a specific API. It could be used for providing arguments for both **cli** and **core** packages. Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.
## Exit codes
The application maintains the following exit codes.
| Exit code | Description |
| --------- | ------------------------ |
| 0 | Success |
| 1 | Command execution error |
| 2 | Config resolving failure |
## Tests
### Unit tests
Unit tests in the **cli** package are sensitive to top-level configuration file (**redocly.yaml**).
To get coverage per package run `npm run coverage:cli` or `npm run coverage:core`.
### E2E tests
E2E tests are sensitive to any additional output (like `console.log`) in the source code.
## Project Structure ## Project Structure
- **`__mocks__`**: contains basic mocks for e2e tests. - **`__mocks__`**: contains basic mocks for e2e tests.
@@ -129,20 +208,3 @@ It only checks links within the local docs (it can't check links to other docs s
- **`packages/core/src/typings`**: contains the common Typescript typings. - **`packages/core/src/typings`**: contains the common Typescript typings.
- **`resources`**: contains some example API definitions and configuration files that might be useful for testing. - **`resources`**: contains some example API definitions and configuration files that might be useful for testing.
## Arguments usage
There are three ways of providing arguments to the CLI: environment variables, command line arguments, and Redocly configuration file.
### Environment variables
Environment variables should be used to provide some arguments that are common for all the commands.
Please avoid using environment variables if possible, as they may lead to ambiguous results. They should not affect the **core** package logic.
### Command line arguments
Use them to provide some arguments that are specific to a certain command. Think of them as modifiers. They should not affect the **core** package logic.
### Configuration file
The **redocly.yaml** file is the most flexible way of providing arguments. Please use it to provide arguments that are common for all the commands, for a specific command, or for a specific API. It could be used for providing arguments for both **cli** and **core** packages. Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.

4
README.md
View File

@@ -83,6 +83,10 @@ If your OpenAPI description isn't everything you hoped it would be, enhance it w
- Improve the docs by adding examples and descriptions - Improve the docs by adding examples and descriptions
- Adapt an existing OpenAPI description, and replace details like URLs for use on staging platforms - Adapt an existing OpenAPI description, and replace details like URLs for use on staging platforms
## Data collection
This tool [collects data](./docs/usage-data.md) to help Redocly improve our products and services. You can opt out by setting the `REDOCLY_TELEMETRY` environment variable to `off`.
## More resources ## More resources
[Read the detailed docs](https://redocly.com/docs/cli/). [Read the detailed docs](https://redocly.com/docs/cli/).

1
docs/commands/join.md
View File

@@ -54,6 +54,7 @@ redocly join --version
| --without-x-tag-groups | boolean | Skip automated `x-tagGroups` creation. See the [without-x-tag-groups](#without-x-tag-groups) section. | | --without-x-tag-groups | boolean | Skip automated `x-tagGroups` creation. See the [without-x-tag-groups](#without-x-tag-groups) section. |
| --version | boolean | Show version number. | | --version | boolean | Show version number. |
| --output, -o | string | Name for the joined output file. Defaults to `openapi.yaml`. **If the file already exists, it's overwritten.** | | --output, -o | string | Name for the joined output file. Defaults to `openapi.yaml`. **If the file already exists, it's overwritten.** |
| --config | string | Specify path to the [config file](../configuration/index.mdx). |
## Examples ## Examples

2
docs/commands/login.md
View File

@@ -33,6 +33,8 @@ Option | Type | Description
--region, -r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. Read more about [configuring the region](../configuration/index.mdx). --region, -r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. Read more about [configuring the region](../configuration/index.mdx).
--verbose | boolean | Include additional output. --verbose | boolean | Include additional output.
--version | boolean | Show version number. --version | boolean | Show version number.
--config | string | Specify path to the [config file](../configuration/index.mdx).
## Examples ## Examples

89
docs/commands/push.md
View File

@@ -69,27 +69,29 @@ To authenticate to the API registry, you can use several approaches:
## Usage ## Usage
```bash ```bash
redocly push [api] <destination> redocly push [api] [--destination] [--organization]
redocly push redocly push
redocly push [-u] [--batch-id id] [--batch-size number] <path/to/definition.yaml> <@organization-id/api-name@api-version> [--branch] redocly push [-u] [--job-id id] [--batch-size number] <path/to/definition.yaml> [--destination] [--organization] [--branch]
``` ```
## Options ## Options
| Option | Type | Description | | Option | Type | Description |
| ---------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ---------------- | :------: |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| api | string | The API definition that you want to push to the Redocly API registry. Provide it as a path to the root API definition file (or as an alias). See [Set options explicitly](#set-options-explicitly) for more information. | | api | string | The API definition that you want to push to the Redocly API registry. Provide it as a path to the root API definition file (or as an alias). See [Set options explicitly](#set-options-explicitly) for more information. |
| destination | string | Conditional. The location in the API registry where you want to push or upsert your API definition. Provide it in the following format: `@organization-id/api-name@api-version` or `api-name@api-version`if organization ID is already defined in the configuration file. See [the Destination section](#destination) for more information. | | --destination | string | The location in the API registry where you want to push or upsert your API definition. Provide it in the following format: `api-name@api-version`. |
| --branch, -b | string | The branch where your API definition is pushed or upserted. Default value is `main`. | | --organization | string | Specifies the ID of organization that the deffenition is being pushed to. Overrides the one defined in the config file. |
| --batch-id | string | Specifies the ID of the CI job that the current push is associated with. See [the Batch ID section](#batch-id) for more information. | | --branch, -b | string | The branch where your API definition is pushed or upserted. Default value is `main`. |
| --batch-size | number | Specifies the total number of CI jobs planned to be pushed within one batch. See [the Batch Size section](#batch-size) for more information. | | --job-id | string | Specifies the ID of the CI job that the current push is associated with. See [the Job ID section](#job-id) for more information. |
| --help | boolean | Help output for the command. | | --batch-size | number | Specifies the total number of CI jobs planned to be pushed within one batch. See [the Batch Size section](#batch-size) for more information. |
| -- public | boolean | Make API definitions publicly accessible from the API Registry. Read more about [using the public option](#public). | | --help | boolean | Help output for the command. |
| --region,-r | string | Specifies which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. Alternatively, set an environment variable `REDOCLY_DOMAIN` with the value the appropriate Redocly API. | | --public | boolean | Make API definitions publicly accessible from the API Registry. Read more about [using the public option](#public). |
| --skip-decorator | [string] | Ignore one or more decorators. See the [Skip decorator section](#skip-decorator) for usage examples. | | --region,-r | string | Specifies which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. Alternatively, set an environment variable `REDOCLY_DOMAIN` with the value the appropriate Redocly API. |
| --upsert, -u | boolean | Upsert an API to the API registry. See [the Upsert an API with push section](#upsert-an-api-with-push) for more information. | | --skip-decorator | [string] | Ignore one or more decorators. See the [Skip decorator section](#skip-decorator) for usage examples. |
| --version | boolean | Show version number. | | --upsert, -u | boolean | Create a new version of an API when pushing to the API registry if the version doesn't exist. See [the Upsert an API with push section](#upsert-an-api-with-push) for more information. |
| --files | [string] | List of other folders and files to upload. See [the Files section](#files) for more information. | | --version | boolean | Show version number. |
| --files | [string] | List of other folders and files to upload. See [the Files section](#files) for more information. |
## Examples ## Examples
The command behaves differently depending on the options you pass to it and whether the configuration file exists in your working directory. The command behaves differently depending on the options you pass to it and whether the configuration file exists in your working directory.
@@ -107,8 +109,6 @@ To properly push your API definition to the Redocly API registry, you need the f
- [API name](#api-name) - [API name](#api-name)
- [API version](#api-version) - [API version](#api-version)
Pass this information to the `push` command in the following format: `@organization-id/api-name@api-version`.
#### Organization ID #### Organization ID
The `push` command uses the following order of precedence: first, it takes the organization ID from command-line arguments (if provided). The `push` command uses the following order of precedence: first, it takes the organization ID from command-line arguments (if provided).
@@ -121,7 +121,7 @@ To find your organization ID required for the command:
1. In your browser's address bar, find the URL of this page. 1. In your browser's address bar, find the URL of this page.
1. Inspect the segment after `app.redocly.com/org/`. This part is your organization ID. 1. Inspect the segment after `app.redocly.com/org/`. This part is your organization ID.
For example, if the URL is `app.redocly.com/org/test_docs`, the organization ID is `test_docs`. When using the `push` command, you would provide this ID as `@test_docs`. For example, if the URL is `app.redocly.com/org/test_docs`, the organization ID is `test_docs`. When using the `push` command, you would provide this ID as `--organization=test_docs`.
:::warning Note :::warning Note
@@ -129,7 +129,7 @@ The organization ID can differ from the organization name. Owners can change the
::: :::
#### API name #### API name and version
To find your API name required for the command: To find your API name required for the command:
@@ -138,16 +138,12 @@ To find your API name required for the command:
1. Check the list of APIs displayed on this page. 1. Check the list of APIs displayed on this page.
1. Inspect the title of each list item to the left of the **New version** and **Edit API** action buttons. This title is an API name. 1. Inspect the title of each list item to the left of the **New version** and **Edit API** action buttons. This title is an API name.
When using the `push` command, you would provide the API name after the [Organization ID](#organization-id) separated with the forward slash (`/`). For example: `@test_docs/petstore-api`.
:::attention :::attention
The name of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created. The name of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
::: :::
#### API version
To find your API version required for the command: To find your API version required for the command:
1. Log into Workflows. 1. Log into Workflows.
@@ -155,8 +151,7 @@ To find your API version required for the command:
1. Check the list of APIs displayed on this page. 1. Check the list of APIs displayed on this page.
1. Inspect the subtitle of each list item to the bottom of the [API name](#api-name). This subtitle is an API version. 1. Inspect the subtitle of each list item to the bottom of the [API name](#api-name). This subtitle is an API version.
When using the `push` command, you would provide the API version after the [API name](#api-name) separated with the "at" symbol (`@`). For example: `@test_docs/petstore-api@v1`. When using the `push` command, you would provide the API name and version separated with the "at" symbol (`@`). For example: `--destination=petstore-api@v1`.
:::attention :::attention
The version of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created. The version of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
@@ -168,7 +163,7 @@ The version of your API should contain only supported characters (`a-z`, `A-Z`,
Provide the `api` as a path to the root API definition file, and specify the organization ID, API name and version. Provide the `api` as a path to the root API definition file, and specify the organization ID, API name and version.
```bash ```bash
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org
``` ```
In this case, `push` uploads only the definition that was passed to the command. The configuration file is ignored. In this case, `push` uploads only the definition that was passed to the command. The configuration file is ignored.
@@ -176,7 +171,7 @@ In this case, `push` uploads only the definition that was passed to the command.
To push the definition to a particular branch, specify the branch name. To push the definition to a particular branch, specify the branch name.
```bash ```bash
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 -b develop redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org -b develop
``` ```
### Set options in the configuration file ### Set options in the configuration file
@@ -202,12 +197,12 @@ Push every API listed in the `apis` section of the configuration file.
You must specify your Workflows organization ID in the configuration file for this approach to work. You must specify your Workflows organization ID in the configuration file for this approach to work.
APIs without an explicitly defined version are automatically pushed to `@latest`. APIs without an explicitly defined version are automatically pushed to `@latest`.
2. `redocly push api-name@api-version` 2. `redocly push --destination=api-name@api-version`
Push the specified API and version from the `apis` section of the configuration file. Push the specified API and version from the `apis` section of the configuration file.
You must specify your organization ID in the configuration file for this approach to work. You must specify your organization ID in the configuration file for this approach to work.
3. `redocly push organization-id/api-name@api-version` 3. `redocly push --destination=api-name@api-version --organization=organization-id`
Push the specified API and version from the `apis` section of the configuration file to the Workflows organization matching the provided organization ID. Push the specified API and version from the `apis` section of the configuration file to the Workflows organization matching the provided organization ID.
In this case, you don't have to specify the organization ID in the configuration file. In this case, you don't have to specify the organization ID in the configuration file.
@@ -217,11 +212,11 @@ In this case, you don't have to specify the organization ID in the configuration
To upsert an API in the registry with the `push` command, use the `--upsert` or `-u` option. To upsert an API in the registry with the `push` command, use the `--upsert` or `-u` option.
```bash Set options explicitly ```bash Set options explicitly
redocly push -u test-api-v1.yaml @redocly/test-api@v1 redocly push -u test-api-v1.yaml --destination=test-api@v1 --organization=redocly
``` ```
```bash Use config file ```bash Use config file
redocly push -u test-api@v1 redocly push -u --destination=test-api@v1
``` ```
```bash Upsert all APIs from config file ```bash Upsert all APIs from config file
@@ -231,18 +226,18 @@ redocly push -u
To upsert the definition to a particular branch, specify the branch name with `--branch` or `-b`. To upsert the definition to a particular branch, specify the branch name with `--branch` or `-b`.
```bash Set options explicitly ```bash Set options explicitly
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 -b develop redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org -b develop
``` ```
```bash Use config file ```bash Use config file
redocly push -u test-api@v1 -b develop redocly push -u test-api@v1 -b develop
``` ```
### Batch ID ### <a name="batch-id"></a>Job ID
The `--batch-id` option can be used by Redocly Workflows to associate multiple pushes with a single CI job. The `--job-id` option can be used by Redocly Workflows to associate multiple pushes with a single CI job.
Below are possible use cases for the `--batch-id` option: Below are possible use cases for the `--job-id` option:
- CI/CD systems: group pushes from a single CI job together so that each push does not trigger separate reference docs/portals rebuild. - CI/CD systems: group pushes from a single CI job together so that each push does not trigger separate reference docs/portals rebuild.
- External systems: a parameter that can be used in reports, metrics, analytics to refer to a specific application service state. - External systems: a parameter that can be used in reports, metrics, analytics to refer to a specific application service state.
@@ -253,18 +248,18 @@ Must be used only in combination with the `--batch-size` option.
The `--batch-size` option can be used by Redocly Workflows to understand how many pushes in total are performed within one batch to properly handle parallel pushes. The `--batch-size` option can be used by Redocly Workflows to understand how many pushes in total are performed within one batch to properly handle parallel pushes.
Must be used only in combination with the `--batch-id` option. Must be an integer bigger than 1. Must be used only in combination with the `--job-id` option. Must be an integer bigger than 1.
### Skip decorator ### Skip decorator
You may want to skip specific decorators upon running the command. You may want to skip specific decorators upon running the command.
```bash Skip a decorator ```bash Skip a decorator
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 --skip-decorator=test/remove-internal-operations redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --skip-decorator=test/remove-internal-operations
``` ```
```bash Skip multiple decorators ```bash Skip multiple decorators
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 --skip-decorator=test/remove-internal-operations --skip-decorator=test/remove-internal-schemas redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --skip-decorator=test/remove-internal-operations --skip-decorator=test/remove-internal-schemas
``` ```
### Public ### Public
@@ -273,7 +268,7 @@ The `--public` option allows you to upload your API definition and make it publi
For more information on how to configure access to your APIs, check the [registry access](../../../api-registry/settings/manage-access/#set-up-access-to-api-registry) section. For more information on how to configure access to your APIs, check the [registry access](../../../api-registry/settings/manage-access/#set-up-access-to-api-registry) section.
```bash ```bash
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 --public redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --public
``` ```
### Files ### Files
@@ -281,10 +276,10 @@ redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 --public
The `--files` option allows you to upload other folders and files. The `--files` option allows you to upload other folders and files.
```bash ```bash
redocly push openapi/petstore.yaml @openapi-org/petstore-api@v1 --files ./path/to/folder redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --files ./path/to/folder
``` ```
You can also add files and folders providing them in `.redocly.yaml`: You can also add files and folders providing them in `redocly.yaml`:
```yaml ```yaml
apis: apis:
@@ -296,7 +291,7 @@ files:
- ./file.md - ./file.md
``` ```
**`--files` has bigger priority than `.redocly.yaml`** **`--files` has higher priority than `redocly.yaml`**
### Set up CI from Redocly Workflows ### Set up CI from Redocly Workflows
@@ -304,10 +299,4 @@ The Redocly Workflows interface can help you get started with the `push` command
1. In **API registry**, select **Add API**. 1. In **API registry**, select **Add API**.
1. In the **Definition name** step, provide a name for your new API definition. 1. In the **Definition name** step, provide a name for your new API definition.
1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API definition file. Or use the `redocly push -u` command directly from the command-line interface. 1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API definition file. Or use the `redocly push -u` command directly from the command-line interface.
## Learn more
- Video tutorial: Using the Redocly CLI push command:
<iframe width="560" height="315" src="https://www.youtube.com/embed/key2NGkcR5g" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

1
docs/commands/split.md
View File

@@ -24,6 +24,7 @@ api | string | **REQUIRED.** Path to the API definition file that you want to sp
--outDir | string | **REQUIRED.** Path to the directory where you want to save split files. If the specified directory doesn't exist, it is created automatically. --outDir | string | **REQUIRED.** Path to the directory where you want to save split files. If the specified directory doesn't exist, it is created automatically.
--help | boolean | Show help. --help | boolean | Show help.
--separator | string | File path separator used while splitting. The default value is `_`. This controls the file names generated in the `paths` folder (e.g. `/users/create` path becomes `user_create.yaml`). --separator | string | File path separator used while splitting. The default value is `_`. This controls the file names generated in the `paths` folder (e.g. `/users/create` path becomes `user_create.yaml`).
--config | string | Specify path to the [config file](../configuration/index.mdx).
--version | boolean | Show version number. --version | boolean | Show version number.
## Example ## Example

22
docs/usage-data.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: Usage data
---
# Usage data and product metrics
Redocly CLI sends a small set of anonymized data to help us understand how the tool is used and improve it.
## What data is collected
When a command is run, the following data is collected:
* the command being run
* command exit code
* values from `REDOCLY_ENVIRONMENT`
* CLI version
* NodeJS version
Values such as file names, organization IDs, and URLs are removed, replaced by just "URL" or "file", etc.
## Opt out of data collection
To opt out, set the `REDOCLY_TELEMETRY` environment variable to `off`, or set `telemetry: off` in the `redocly.yaml` configuration file.