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

sync: Synced local 'docs/' with remote 'docs/cli/'

Browse Source
This commit is contained in:
redocly-bot
2022-05-04 19:32:45 +00:00
parent d7ed5092e8
commit f4db5622b3
8 changed files with 290 additions and 306 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/commands/lint.md
View File

@@ -95,7 +95,7 @@ If you try to execute the `lint` command without entrypoints when your project d
### Custom configuration file
By default, the CLI tool looks for the [Redocly configuration file](/docs/cli/configuration/configuration-file.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
By default, the CLI tool looks for the [Redocly configuration file](/docs/cli/configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
```bash
openapi lint --config=./another/directory/config.yaml

2
docs/commands/login.md
View File

@@ -32,7 +32,7 @@ Option | Type | Description
--help | boolean | Show help.
--verbose | boolean | Include additional output.
--version | boolean | Show version number.
--region, -r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. Read more about [configuring the region](../configuration/configuration-file.mdx#region).
--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).
## Examples

2
docs/commands/preview-docs.md
View File

@@ -66,7 +66,7 @@ In this case, after resolving the path behind the `core@v1` name (see the `Confi
### Custom configuration file
By default, the CLI tool looks for the [Redocly configuration file](/docs/cli/configuration/configuration-file.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
By default, the CLI tool looks for the [Redocly configuration file](/docs/cli/configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
```bash
openapi preview-docs --config=./another/directory/config.yaml

6
docs/commands/push.md
View File

@@ -13,7 +13,7 @@ This allows you to:
Apart from uploading your API definition file, the `push` command can automatically upload other files if they are detected or referenced in the API definition:
- the [Redocly configuration file](/docs/cli/configuration/configuration-file.mdx).
- the [Redocly configuration file](/docs/cli/configuration/index.mdx).
- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows will use the `@redocly/openapi-cli` version specified in `package.json`.
- the HTML template and the full contents of the folder specified as the `features.openapi > htmlTemplate` parameter in the Redocly configuration file.
@@ -77,7 +77,7 @@ openapi push [-u] [--run-id id] <path/to/definition.yaml> <@organization-id/api-
## Options
Option | Type | Description |
-----------------|:---------:|:------------:|
-----------------|:---------:|------------|
entrypoint | 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. |
--branch, -b | string | The branch where your API definition will be pushed or upserted. Default value is `main`. |
@@ -86,7 +86,7 @@ destination | string | Conditional. The location in the API registry whe
--skip-decorator | [string] | Ignore one or more decorators. See the [Skip decorator section](#skip-decorator) for usage examples.
--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. |
--version | boolean | Show version number. |
--region,-r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. Default value is `us`. Read more about [configuring the region](../configuration/configuration-file.mdx#region).
--region,-r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. Read more about [configuring the region](../configuration/index.mdx#region).
## Examples

16
docs/commands/stats.md
View File

@@ -23,13 +23,13 @@ openapi stats --version
## Options
Option | Type | Required | Default | Description
--------------------------|:---------:|:------------:|:-----------:|------------
`entrypoint` | `string` | yes | - | Path to the API definition filename that you want to calculate statistics for. Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file as entrypoints. Refer to [the entrypoint section below](#entrypoint) for more options.
`--config` | `string` | no | - | Specify path to the [configuration file](#custom-configuration-file)
`--format` | `string` | no | `stylish` | Format for the output.<br />**Possible values:** `stylish`, `json`
`--help` | `boolean` | no | - | Show help
`--version` | `boolean` | no | - | Show version number
Option | Type | Description
-- | -- | --
entrypoint | string | **REQUIRED.** Path to the API definition file that you want to split into a multi-file structure.
--config | string | Specify path to the [configuration file](#custom-configuration-file).
--format | string | Format for the output.<br />**Possible values:** `stylish`, `json`.
--help | boolean | Show help.
--version | boolean | Show version number.
## Examples
@@ -64,7 +64,7 @@ In this case, after resolving the path behind the `core@v1` name (see the `Confi
### Custom configuration file
By default, the CLI tool looks for the [Redocly configuration file](/docs/cli/configuration/configuration-file.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
By default, the CLI tool looks for the [Redocly configuration file](/docs/cli/configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
```bash
openapi stats --config=./another/directory/config.yaml

276
docs/configuration/configuration-file.mdx
View File

@@ -1,276 +0,0 @@
import { JsonSchema } from '@redocly/developer-portal/ui';
import Schema from './schema.yaml';
import { StyledContent } from '../../components/styled.elements';
# Redocly configuration file
The Redocly configuration file controls options for the OpenAPI CLI tool.
It is also used across other Redocly products to help you control their behavior.
- Workflows uses it in the API registry to manage your APIs and control advanced features like region and link resolution.
- Reference uses it to apply your custom settings when building API reference documentation (hosted and on-premise).
- VS Code extension uses it for linting criteria, to apply custom settings for live documentation preview, and to set API definition root files.
## Filename and location
The Redocly configuration file must be named `redocly.yaml` or `.redocly.yaml`, and placed into your working directory or the root of your project (depending on the Redocly product you're using).
OpenAPI CLI will search for the configuration file in the working directory.
:::warning
Multiple configuration files in the same directory are not allowed.
If you have a `redocly.yaml` and a `.redocly.yaml` file in the same directory, Redocly apps will display a warning in the output and ask you to choose one file to use.
:::
## File format and structure
The Redocly configuration file must be in YAML format.
<StyledContent>
<JsonSchema
schema={Schema}
options={{
schemaExpansionLevel:3,
}}
/>
</StyledContent>
### Example
```yaml
organization: testing_redocly
apis:
core@v2:
root: ./openapi/openapi.yaml
lint:
rules:
example-rule: warn
external@v1:
root: ./openapi/external.yaml
labels:
- external
features.openapi:
hideLogo: true
lint:
extends:
- recommended
features.openapi:
schemaExpansionLevel: 2
generateCodeSamples:
languages:
- lang: curl
- lang: Python
```
### organization
The `organization` property requires the organization ID of your Redocly Workflows organization.
When specified in the configuration file, it can be used by the `openapi push` command.
The `push` command uses the following order of precedence: first, it takes the organization ID from command-line arguments (if provided).
If the organization ID is not provided explicitly, it takes it from the configuration file.
Note that the organization ID is not the same as the organization name in Workflows.
To find the organization ID, log into Workflows and access the **API registry** page.
In your browser's address bar, find the URL of the page.
The segment after `app.redocly.com/org/` is your organization ID.
For example, if the URL is `app.redocly.com/org/test_docs`, the organization ID is `test_docs`.
### apis
The `apis` section is used to configure one or more APIs. Every API in the section is identified by its name and version in the format `name@version`. The version is optional, and when not provided, Redocly apps interpret it as `latest` by default. Every `name@version` combination listed in the section must be unique.
For every API listed in the section, you must provide the path to the OpenAPI definition using the `root` property.
```yaml
apis:
name@version:
root: ./openapi/openapi.yaml
labels:
- production
lint: []
features.openapi: []
lint:
rules:
example-rule-name: error
features.openapi:
pagination: section
showConsole: true
theme:
menu:
backgroundColor: '#fffff'
```
The `apis` section supports several optional properties for every listed API.
**labels**
Use it to assign one or more existing Redocly Workflows organization-wide labels to your APIs. You must have a Redocly Workflows account with an active organization, and add the top-level `organization` property to the configuration file.
If you try to assign labels that don't already exist for your organization, Redocly apps will display a warning in the output and will only assign the existing labels (if any).
**lint**
In addition to the global (top-level) `lint` section, you can add one to each API listed in `apis`. This allows you to use different rules and decorators for different APIs.
**features.openapi**
In addition to the global (top-level) `features.openapi` section, you can add one to each API listed in `apis`. This allows you to use different API reference docs settings for different APIs.
This section supports identical format and options as the global `features.openapi` section.
:::warning Important
Not all `lint` options are supported in per-API configuration.
Consult the table below to understand how each configuration section applies to your APIs.
:::
Configuration section | Per-API support | Behavior
-- | -- | --
lint.extends | ❗ | API settings override global settings.
lint.rules | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.decorators | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.preprocessors | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.plugins | ❌ | Available in global configuration only.
features.openapi | ✅ | API and global settings merge. In case of conflict, API takes priority.
features.mockServer | ✅ | API and global settings merge. In case of conflict, API takes priority.
Some of the OpenAPI CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` section as shortcuts for referencing API definitions.
You can tell the `lint` command to validate specific API definitions by using their names from the `apis` section, like in the following example:
```shell
openapi lint core
```
On the other hand, if you run the command without specifying any aliases, it will apply to all API definitions listed in the `apis` section:
```shell
openapi lint
```
### lint
The `lint` section's primary purpose is to define options for the `lint` and `bundle` commands.
You may also import plugins and extends their configurations.
Read more about the [lint configuration section](../guides/lint.md).
### features.mockServer
The API registry supports [the mock server feature](../../api-registry/guides/mock-server-quickstart.md) and allows project owners to enable it for all branches per API version.
When the mock server is enabled for an API, you can send test requests to it from any API client.
The `features.mockServer` section allows additional configuration of the mock server behavior.
This section is optional.
The `features.mockServer` section supports fields listed in the following table.
| Property | Description | Default |
| --- | --- | --- |
| errorIfForcedExampleNotFound | Users can force specific examples in the response by adding the optional `x-redocly-response-body-example` header to their requests. By default, if an example ID provided in the request is not found in the API definition, the mock server returns any other example. If you set `errorIfForcedExampleNotFound: true`, the mock server will return an error instead. | false |
| strictExamples | By default, the mock server automatically enhances responses with heuristics like substituting the response fields with request parameter values. To prevent this behavior, set `strictExamples: true`. When this is set, examples are returned in the response unmodified, exactly how they are defined in the OpenAPI document. | false |
### region
For optimized performance or for compliance purposes, you can specify which region to use when logging into Redocly services (such as the API registry). Supported regions are `us` (used by default) and `eu`.
You should log into the region that corresponds to your Redocly Workflows organization. If you're a member of multiple organizations in different regions, it's technically possible to log into two different regions at the same time, but it's neither the most common nor the recommended use-case.
Every supported region uses its own domain.
Region | Domain
-----|:---------
`us` | api.redoc.ly
`eu` | api.eu.redocly.com
The `eu` region is limited to enterprise customers.
To configure which domain will be used, you can use any of the following:
- the `REDOCLY_DOMAIN` environment variable
```sh
export REDOCLY_DOMAIN={domain}
```
- the `--region` option with `login` and `push` commands
```sh
openapi login --region=eu
```
- the `region` top-level property in the Redocly configuration file
```yaml
apis:
core@v1:
root: ./openapi.yaml
region: eu
lint:
extends: []
```
### resolve
Redocly will automatically resolve any API registry link or public URL in your API definitions. However, you may want to resolve links that are not API registry links or publicly accessible. To accomplish that, add the `resolve` section to the configuration file.
OpenAPI CLI only supports `http` headers. Only one `http` header per URL is supported in the `resolve` section.
We recommend using environment variables whenever possible.
#### Resolving external links
The `resolve` section should be structured like this:
```yaml
resolve:
http:
headers:
- # header configuration
```
The `headers` section supports fields listed in the following table.
| Property | Description | Examples |
| --- | --- | --- |
| matches | Glob match against the URL. | `https://api.example.com/**` or `https://api.example.com/*.json`|
| name | HTTP header name. | `Authorization` or `X-API-KEY`|
| value | The value of the header. Mutually exclusive with `envVariable`. | `123-abc`|
| envVariable | The name of the environment variable that contains the value of the header. Mutually exclusive with `value`. |`SECRET_KEY`|
Here is a structured example for adding header definitions:
```yaml
resolve:
http:
headers:
- matches: https://api.example.com/v2/**
name: X-API-KEY
envVariable: SECRET_KEY
- matches: https://example.com/*/test.yaml
name: Authorization
envVariable: SECRET_AUTH
```
The first match takes precedence when a URL matches multiple patterns. Therefore, only the header from the first match will be used in the request.
### features.openapi
The `features.openapi` section configures features (availability and options) and theming (style, fonts, colors) for API reference documentation generated from API definitions.
There are two products: Redoc Community Edition (CE) and Redocly Reference. Reference supports all configuration options from Redoc Community Edition plus a set of premium options.
Find the full list of supported options on the [Reference docs configuration page](../../api-reference-docs/configuration/index.mdx).

285
docs/configuration/index.mdx
View File

@@ -1,16 +1,283 @@
---
title: OpenAPI CLI configuration
description: Learn how to configure OpenAPI CLI
redirectFrom:
- /docs/cli/configuration/configuration-file/
---
import { WideTile, Flex } from '@redocly/developer-portal/ui';
import { JsonSchema } from '@redocly/developer-portal/ui';
import Schema from './schema.yaml';
import { StyledContent } from '../../components/styled.elements';
# OpenAPI CLI configuration
<div>
<Flex justifyContent="space-between" flexWrap="wrap">
<WideTile to="./configuration-file.mdx" header="Redocly configuration file">
Customize the config file and get OpenAPI CLI working even harder for you!
</WideTile>
</Flex>
</div>
# Redocly configuration file
The Redocly configuration file controls options for the OpenAPI CLI tool.
It is also used across other Redocly products to help you control their behavior.
- Workflows uses it in the API registry to manage your APIs and control advanced features like region and link resolution.
- Reference uses it to apply your custom settings when building API reference documentation (hosted and on-premise).
- VS Code extension uses it for linting criteria, to apply custom settings for live documentation preview, and to set API definition root files.
## Filename and location
The Redocly configuration file must be named `redocly.yaml` or `.redocly.yaml`, and placed into your working directory or the root of your project (depending on the Redocly product you're using).
OpenAPI CLI will search for the configuration file in the working directory.
:::warning
Multiple configuration files in the same directory are not allowed.
If you have a `redocly.yaml` and a `.redocly.yaml` file in the same directory, Redocly apps will display a warning in the output and ask you to choose one file to use.
:::
## File format and structure
The Redocly configuration file must be in YAML format.
<StyledContent>
<JsonSchema
schema={Schema}
options={{
schemaExpansionLevel:3,
}}
/>
</StyledContent>
### Example
```yaml
organization: testing_redocly
apis:
core@v2:
root: ./openapi/openapi.yaml
lint:
rules:
example-rule: warn
external@v1:
root: ./openapi/external.yaml
labels:
- external
features.openapi:
hideLogo: true
lint:
extends:
- recommended
features.openapi:
schemaExpansionLevel: 2
generateCodeSamples:
languages:
- lang: curl
- lang: Python
```
### organization
The `organization` property requires the organization ID of your Redocly Workflows organization.
When specified in the configuration file, it can be used by the `openapi push` command.
The `push` command uses the following order of precedence: first, it takes the organization ID from command-line arguments (if provided).
If the organization ID is not provided explicitly, it takes it from the configuration file.
Note that the organization ID is not the same as the organization name in Workflows.
To find the organization ID, log into Workflows and access the **API registry** page.
In your browser's address bar, find the URL of the page.
The segment after `app.redocly.com/org/` is your organization ID.
For example, if the URL is `app.redocly.com/org/test_docs`, the organization ID is `test_docs`.
### apis
The `apis` section is used to configure one or more APIs. Every API in the section is identified by its name and version in the format `name@version`. The version is optional, and when not provided, Redocly apps interpret it as `latest` by default. Every `name@version` combination listed in the section must be unique.
For every API listed in the section, you must provide the path to the OpenAPI definition using the `root` property.
```yaml
apis:
name@version:
root: ./openapi/openapi.yaml
labels:
- production
lint: []
features.openapi: []
lint:
rules:
example-rule-name: error
features.openapi:
pagination: section
showConsole: true
theme:
menu:
backgroundColor: '#fffff'
```
The `apis` section supports several optional properties for every listed API.
**labels**
Use it to assign one or more existing Redocly Workflows organization-wide labels to your APIs. You must have a Redocly Workflows account with an active organization, and add the top-level `organization` property to the configuration file.
If you try to assign labels that don't already exist for your organization, Redocly apps will display a warning in the output and will only assign the existing labels (if any).
**lint**
In addition to the global (top-level) `lint` section, you can add one to each API listed in `apis`. This allows you to use different rules and decorators for different APIs.
**features.openapi**
In addition to the global (top-level) `features.openapi` section, you can add one to each API listed in `apis`. This allows you to use different API reference docs settings for different APIs.
This section supports identical format and options as the global `features.openapi` section.
:::warning Important
Not all `lint` options are supported in per-API configuration.
Consult the table below to understand how each configuration section applies to your APIs.
:::
Configuration section | Per-API support | Behavior
-- | -- | --
lint.extends | ❗ | API settings override global settings.
lint.rules | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.decorators | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.preprocessors | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.plugins | ❌ | Available in global configuration only.
features.openapi | ✅ | API and global settings merge. In case of conflict, API takes priority.
features.mockServer | ✅ | API and global settings merge. In case of conflict, API takes priority.
Some of the OpenAPI CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` section as shortcuts for referencing API definitions.
You can tell the `lint` command to validate specific API definitions by using their names from the `apis` section, like in the following example:
```shell
openapi lint core
```
On the other hand, if you run the command without specifying any aliases, it will apply to all API definitions listed in the `apis` section:
```shell
openapi lint
```
### lint
The `lint` section's primary purpose is to define options for the `lint` and `bundle` commands.
You may also import plugins and extends their configurations.
Read more about the [lint configuration section](../guides/lint.md).
### features.mockServer
The API registry supports [the mock server feature](../../api-registry/guides/mock-server-quickstart.md) and allows project owners to enable it for all branches per API version.
When the mock server is enabled for an API, you can send test requests to it from any API client.
The `features.mockServer` section allows additional configuration of the mock server behavior.
This section is optional.
The `features.mockServer` section supports fields listed in the following table.
| Property | Description | Default |
| --- | --- | --- |
| errorIfForcedExampleNotFound | Users can force specific examples in the response by adding the optional `x-redocly-response-body-example` header to their requests. By default, if an example ID provided in the request is not found in the API definition, the mock server returns any other example. If you set `errorIfForcedExampleNotFound: true`, the mock server will return an error instead. | false |
| strictExamples | By default, the mock server automatically enhances responses with heuristics like substituting the response fields with request parameter values. To prevent this behavior, set `strictExamples: true`. When this is set, examples are returned in the response unmodified, exactly how they are defined in the OpenAPI document. | false |
### region
For optimized performance or for compliance purposes, you can specify which region to use when logging into Redocly services (such as the API registry). Supported regions are `us` (used by default) and `eu`.
You should log into the region that corresponds to your Redocly Workflows organization. If you're a member of multiple organizations in different regions, it's technically possible to log into two different regions at the same time, but it's neither the most common nor the recommended use-case.
Every supported region uses its own domain.
Region | Domain
-----|:---------
`us` | api.redoc.ly
`eu` | api.eu.redocly.com
The `eu` region is limited to enterprise customers.
To configure which domain will be used, you can use any of the following:
- the `REDOCLY_DOMAIN` environment variable
```sh
export REDOCLY_DOMAIN={domain}
```
- the `--region` option with `login` and `push` commands
```sh
openapi login --region=eu
```
- the `region` top-level property in the Redocly configuration file
```yaml
apis:
core@v1:
root: ./openapi.yaml
region: eu
lint:
extends: []
```
### resolve
Redocly will automatically resolve any API registry link or public URL in your API definitions. However, you may want to resolve links that are not API registry links or publicly accessible. To accomplish that, add the `resolve` section to the configuration file.
OpenAPI CLI only supports `http` headers. Only one `http` header per URL is supported in the `resolve` section.
We recommend using environment variables whenever possible.
#### Resolving external links
The `resolve` section should be structured like this:
```yaml
resolve:
http:
headers:
- # header configuration
```
The `headers` section supports fields listed in the following table.
| Property | Description | Examples |
| --- | --- | --- |
| matches | Glob match against the URL. | `https://api.example.com/**` or `https://api.example.com/*.json`|
| name | HTTP header name. | `Authorization` or `X-API-KEY`|
| value | The value of the header. Mutually exclusive with `envVariable`. | `123-abc`|
| envVariable | The name of the environment variable that contains the value of the header. Mutually exclusive with `value`. |`SECRET_KEY`|
Here is a structured example for adding header definitions:
```yaml
resolve:
http:
headers:
- matches: https://api.example.com/v2/**
name: X-API-KEY
envVariable: SECRET_KEY
- matches: https://example.com/*/test.yaml
name: Authorization
envVariable: SECRET_AUTH
```
The first match takes precedence when a URL matches multiple patterns. Therefore, only the header from the first match will be used in the request.
### features.openapi
The `features.openapi` section configures features (availability and options) and theming (style, fonts, colors) for API reference documentation generated from API definitions.
There are two products: Redoc Community Edition (CE) and Redocly Reference. Reference supports all configuration options from Redoc Community Edition plus a set of premium options.
Find the full list of supported options on the [Reference docs configuration page](../../api-reference-docs/configuration/index.mdx).

7
docs/configuration/registry.md
View File

@@ -1,7 +0,0 @@
# Registry
The Redocly API registry is part of the [Workflows app](https://app.redocly.com/).
There are no extra Redocly configuration file controls for the registry.
The registry uses the Redocly configuration file for linting, and to control the features and styles of API reference documentation.