mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-06 12:47:48 +00:00
chore: rename package to @redocly/cli (#672)
Co-authored-by: Andrew Tatomyr <andrew.tatomyr@gmail.com> Co-authored-by: Ivana Isadora Devcic <skadinna@gmail.com>
This commit is contained in:
Roman Hotsiy
12
.github/CONTRIBUTING.md
vendored
12
.github/CONTRIBUTING.md
vendored
@@ -1,8 +1,8 @@
|
||||
# OpenAPI CLI Contributing Guide
|
||||
# Redocly CLI Contributing Guide
|
||||
|
||||
Hi! We're really excited that you are interested in contributing to OpenAPI CLI. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
|
||||
Hi! We're really excited that you are interested in contributing to Redocly CLI. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
|
||||
|
||||
- [OpenAPI CLI Contributing Guide](#openapi-cli-contributing-guide)
|
||||
- [Redocly CLI Contributing Guide](#redocly-cli-contributing-guide)
|
||||
- [Issue Reporting Guidelines](#issue-reporting-guidelines)
|
||||
- [Pull Request Guidelines](#pull-request-guidelines)
|
||||
- [Development Setup](#development-setup)
|
||||
@@ -11,7 +11,7 @@ Hi! We're really excited that you are interested in contributing to OpenAPI CLI.
|
||||
|
||||
## Issue Reporting Guidelines
|
||||
|
||||
- Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that by going to the [Issues page](https://github.com/Redocly/openapi-cli/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one!
|
||||
- Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that by going to the [Issues page](https://github.com/Redocly/redocly-cli/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one!
|
||||
|
||||
- The best way to get your bug fixed is to provide a (reduced) test case. This means listing and explaining the steps we should take to try and hit the same problem you're having. It helps us understand in which conditions the issue appears, and gives us a better idea of what may be causing it.
|
||||
|
||||
@@ -81,7 +81,7 @@ There are some other scripts available in the `scripts` section of the `package.
|
||||
|
||||
- **`packages`**: contains the source code. Сonsists of two packages - CLI and core. The codebase is written in Typescript.
|
||||
|
||||
- **`packages/cli`**: contains OpenAPI CLI commands and utils. More details [here](../packages/cli/README.md).
|
||||
- **`packages/cli`**: contains Redocly CLI commands and utils. More details [here](../packages/cli/README.md).
|
||||
|
||||
- **`packages/cli/src`**: contains CLI package source code.
|
||||
|
||||
@@ -89,7 +89,7 @@ There are some other scripts available in the `scripts` section of the `package.
|
||||
- **`packages/cli/src/__tests__`**: contains unit tests.
|
||||
- **`packages/cli/src/commands`**: contains CLI commands functions.
|
||||
|
||||
- **`packages/core`**: contains OpenAPI CLI core functionality like rules, decorators, etc.
|
||||
- **`packages/core`**: contains Redocly CLI core functionality like rules, decorators, etc.
|
||||
|
||||
- **`packages/core/__tests__`**: contains unit tests.
|
||||
- **`packages/cli/core`**: contains core package source code.
|
||||
|
||||
4
.github/ISSUE_TEMPLATE/bug_report.md
vendored
4
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@@ -27,8 +27,8 @@ If applicable, add logs to help explain your problem.
|
||||
If applicable, add an OpenAPI definition and `.redocly.yaml` configuration file that helps reproduce the problem.
|
||||
At a minimum, please state the specification version(s) you're using (e.g. 2.0, 3.0, 3.1).
|
||||
|
||||
**`openapi-cli` Version(s)**
|
||||
What version of `openapi-cli` are you using?
|
||||
**Redocly Version(s)**
|
||||
What version of Redocly CLI are you using?
|
||||
|
||||
**`Node.js` Version(s)**
|
||||
What version of `node.js` are you using?
|
||||
|
||||
24
README.md
24
README.md
@@ -1,16 +1,16 @@
|
||||
# OpenAPI CLI toolset
|
||||
# Redocly CLI toolset
|
||||
|
||||
OpenAPI CLI toolbox with rich validation and bundling features.
|
||||
Redocly CLI toolbox with rich validation and bundling features.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
Currently, @redocly/openapi-cli supports these features:
|
||||
Currently, @redocly/cli supports these features:
|
||||
|
||||
- [x] Multi-file validation. No need to bundle your file before validation.
|
||||
- [x] Lightning-fast validation. Lint a 1 MB file in less than one second.
|
||||
@@ -27,25 +27,25 @@ Currently, @redocly/openapi-cli supports these features:
|
||||
|
||||
## What makes this tool different
|
||||
|
||||
Unlike other OpenAPI linters, `@redocly/openapi-cli` defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how linters for programming languages work and results in major performance benefits over other approaches. Extend functionality at different points in the lifecycle with preprocessors, rules, and decorators.
|
||||
Unlike other OpenAPI linters, `@redocly/cli` defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how linters for programming languages work and results in major performance benefits over other approaches. Extend functionality at different points in the lifecycle with preprocessors, rules, and decorators.
|
||||
|
||||
## Usage
|
||||
|
||||
### Node
|
||||
|
||||
```
|
||||
npx @redocly/openapi-cli lint path-to-root-file.yaml
|
||||
npx @redocly/cli lint path-to-root-file.yaml
|
||||
```
|
||||
|
||||
Alternatively, install it globally with `npm`:
|
||||
|
||||
```
|
||||
npm install @redocly/openapi-cli -g
|
||||
npm install @redocly/cli -g
|
||||
```
|
||||
|
||||
Then you can use it as `openapi [command] [options]`, for example:
|
||||
Then you can use it as `redocly [command] [options]`, for example:
|
||||
|
||||
```openapi lint path-to-root-file.yaml```
|
||||
```redocly lint path-to-root-file.yaml```
|
||||
|
||||
### Docker
|
||||
|
||||
|
||||
@@ -2,19 +2,53 @@
|
||||
tocMaxDepth: 2
|
||||
---
|
||||
|
||||
# OpenAPI CLI changelog
|
||||
# Redocly CLI changelog
|
||||
|
||||
## 1.0.0-beta-95 (2022-05-04)
|
||||
|
||||
:::warning Product name change
|
||||
|
||||
The product name has changed from OpenAPI CLI to **Redocly CLI**.
|
||||
|
||||
You will notice this change reflected in all Redocly product documentation, in the npm package name (more on that in the "Deprecated" section),
|
||||
and later in the official project GitHub repository.
|
||||
|
||||
The change also affects the CLI commands. The legacy name `openapi` will remain supported for a while, but we strongly recommend you use the new name `redocly`.
|
||||
(To illustrate, if you previously used `openapi lint`, now you should use `redocly lint`).
|
||||
|
||||
If you encounter any issues and suspect they may be related to this change, let us know by [reporting an issue](https://github.com/Redocly/openapi-cli/issues).
|
||||
|
||||
:::
|
||||
|
||||
### Features
|
||||
|
||||
- Added support for files in Redocly config `extends` section.
|
||||
- Added codeclimate formating for lint command.
|
||||
- Internal changes.
|
||||
- The `lint.extends` section in the Redocly configuration file supports file paths and URLs as values. This means you can define your own lint rulesets in local or remote files, and list those files in the `extends` section. The following example shows how to do it:
|
||||
|
||||
```yaml
|
||||
lint:
|
||||
extends:
|
||||
- recommended
|
||||
- ./path/to/local/lint-ruleset.yaml
|
||||
- https://url-to-remote/lint-ruleset.yaml
|
||||
```
|
||||
|
||||
The contents of those referenced files must correspond to the standard format used in the `lint.rules` section to configure the rules. Here is an example `lint-ruleset.yaml` file referenced above:
|
||||
|
||||
```yaml
|
||||
lint:
|
||||
rules:
|
||||
tags-alphabetical: error
|
||||
```
|
||||
|
||||
- The `lint` command supports a new output formatting option called `codeclimate` that you can use with the `--format` argument.
|
||||
|
||||
### Fixes
|
||||
|
||||
- Fixed resolving scalar values in asserts.
|
||||
- Fixed an issue with resolvable scalar values not working in assertions.
|
||||
|
||||
### Deprecated
|
||||
|
||||
- Deprecated the `@redocly/openapi-cli` npm package. From this version forward, use `@redocly/cli` instead.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
API definitions can grow and become difficult to manage, especially if several teams are collaborating on them. It's a good practice to maintain the reusable parts as separate files, and include them in the main (root) API definition by referencing them with `$ref`. However, most OpenAPI tools don't support that multi-file approach, and require a single-file API definition.
|
||||
|
||||
Redocly OpenAPI CLI can help you combine separate API definition files into one. The `bundle` command pulls the relevant parts of an API definition into a single file output in JSON or YAML format.
|
||||
Redocly CLI can help you combine separate API definition files into one. The `bundle` command pulls the relevant parts of an API definition into a single file output in JSON or YAML format.
|
||||
|
||||
The `bundle` command first executes preprocessors, then rules, then decorators.
|
||||
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
tocMaxDepth: 2
|
||||
---
|
||||
|
||||
# OpenAPI CLI commands
|
||||
# Redocly CLI commands
|
||||
|
||||
Redocly OpenAPI CLI currently supports the following commands:
|
||||
Redocly CLI currently supports the following commands:
|
||||
|
||||
* [bundle](bundle.md)
|
||||
* [join](join.md)
|
||||
@@ -16,11 +16,11 @@ Redocly OpenAPI CLI currently supports the following commands:
|
||||
* [split](split.md)
|
||||
* [stats](stats.md)
|
||||
|
||||
OpenAPI CLI comes with one primary configuration file (`redocly.yaml`), also known as the Redocly configuration file.
|
||||
Redocly CLI comes with one primary configuration file (`redocly.yaml`), also known as the Redocly configuration file.
|
||||
This file defines all of the config options available to you, including the location of your files (for unbundling and bundling), and linting rules (for validation against the OpenAPI Specification).
|
||||
|
||||
The Redocly configuration file must sit in your root directory (`openapi` by default unless you renamed it).
|
||||
If OpenAPI CLI finds `redocly.yaml` in the root directory, it will use the options set in that file when executing commands.
|
||||
If Redocly CLI finds `redocly.yaml` in the root directory, it will use the options set in that file when executing commands.
|
||||
|
||||
For more information, refer to the [Redocly configuration file](../configuration/index.mdx) docs.
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ The `join` command supports OpenAPI 3.x definitions only.
|
||||
|
||||
Maintainers of multiple API definitions can benefit from storing each endpoint as a standalone API definition file. However, this approach is not supported by the majority of OpenAPI tools, as they require a single API definition file.
|
||||
|
||||
With Redocly OpenAPI CLI, you can solve this problem by using the `join` command that can combine two or more API definition files into a single one.
|
||||
With Redocly CLI, you can solve this problem by using the `join` command that can combine two or more API definition files into a single one.
|
||||
|
||||
To easily distinguish the origin of OpenAPI objects and properties, you can optionally instruct the `join` command to append custom prefixes to them.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Introduction
|
||||
|
||||
Redocly OpenAPI CLI can identify and report on problems found in OpenAPI definitions. This helps you avoid bugs and make API definitions more consistent.
|
||||
Redocly CLI can identify and report on problems found in OpenAPI definitions. This helps you avoid bugs and make API definitions more consistent.
|
||||
|
||||
The `lint` command reports on problems and executes preprocessors and rules. Unlike the `bundle` command, `lint` doesn't execute decorators.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
Redocly Workflows integrates with [popular version control services](../../workflows/sources/index.md) and uses them as the source of your API definitions to help you automatically validate, build, and deploy API reference docs and developer portals. This approach requires you to give Redocly Workflows access to your repositories.
|
||||
|
||||
The OpenAPI CLI `push` command helps you automate API definition updates without granting Redocly Workflows access to your repositories. This is useful when you can't or don't want to grant Redocly Workflows permissions to your repositories, or when your API definitions are generated automatically from code annotations in a CI/CD pipeline
|
||||
The Redocly CLI `push` command helps you automate API definition updates without granting Redocly Workflows access to your repositories. This is useful when you can't or don't want to grant Redocly Workflows permissions to your repositories, or when your API definitions are generated automatically from code annotations in a CI/CD pipeline
|
||||
|
||||
This allows you to:
|
||||
|
||||
@@ -14,7 +14,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/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 `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows will use the `@redocly/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.
|
||||
|
||||
:::attention
|
||||
@@ -271,6 +271,6 @@ The Redocly Workflows interface can help you get started with the `push` command
|
||||
|
||||
## Learn more
|
||||
|
||||
- Video tutorial: Using the OpenAPI CLI push command:
|
||||
- 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,6 +1,6 @@
|
||||
---
|
||||
title: OpenAPI CLI configuration
|
||||
description: Learn how to configure OpenAPI CLI
|
||||
title: Redocly CLI configuration
|
||||
description: Learn how to configure Redocly CLI
|
||||
redirectFrom:
|
||||
- /docs/cli/configuration/configuration-file/
|
||||
---
|
||||
@@ -9,10 +9,9 @@ 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.
|
||||
The Redocly configuration file controls options for the Redocly 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.
|
||||
@@ -23,7 +22,7 @@ It is also used across other Redocly products to help you control their behavior
|
||||
|
||||
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.
|
||||
Redocly CLI will search for the configuration file in the working directory.
|
||||
|
||||
:::warning
|
||||
|
||||
@@ -151,7 +150,7 @@ features.openapi | ✅ | API and global settings merge. In case of conflict, API
|
||||
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.
|
||||
Some of the Redocly 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
|
||||
@@ -233,7 +232,7 @@ lint:
|
||||
|
||||
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.
|
||||
Redocly CLI only supports `http` headers. Only one `http` header per URL is supported in the `resolve` section.
|
||||
|
||||
We recommend using environment variables whenever possible.
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Estimated time: 20 minutes
|
||||
const ChangeTokenUrl = require('./decorators/change-token-url');
|
||||
const id = 'acme';
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
|
||||
/** @type {import('@redocly/cli').CustomRulesConfig} */
|
||||
const decorators = {
|
||||
oas3: {
|
||||
'change-token-url': ChangeTokenUrl,
|
||||
@@ -46,7 +46,7 @@ Estimated time: 20 minutes
|
||||
```js decorators/change-token-url.js
|
||||
module.exports = ChangeTokenUrl;
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').OasDecorator} */
|
||||
/** @type {import('@redocly/cli').OasDecorator} */
|
||||
function ChangeTokenUrl() {
|
||||
return {
|
||||
SecuritySchemeFlows: {
|
||||
|
||||
@@ -31,7 +31,7 @@ The following image highlights what we'll remove in this tutorial.
|
||||
This tutorial is most effective when you follow along and complete the steps.
|
||||
:::
|
||||
|
||||
- [Install @redocly/openapi-cli](../installation.md) with version 1.0.0-beta.90 or later (we use 1.0.0-beta.94 in this tutorial).
|
||||
- [Install @redocly/cli](../installation.md) with version 1.0.0-beta.90 or later (we use 1.0.0-beta.94 in this tutorial).
|
||||
- Download the [sample.yaml](https://gist.github.com/adamaltman/ee07bf94a967926ee0e54bcd56fdcdfb) file into a new directory named `hide-apis-demo`.
|
||||
- Use your favorite IDE for editing the YAML file (we use VS Code and have the [Redocly extension](../../redocly-openapi/index.md) installed).
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
title: OpenAPI CLI guides
|
||||
description: Browse how-to guides for working with OpenAPI CLI
|
||||
title: Redocly CLI guides
|
||||
description: Browse how-to guides for working with Redocly CLI
|
||||
---
|
||||
|
||||
import { WideTile, Flex } from '@redocly/developer-portal/ui';
|
||||
|
||||
# OpenAPI CLI guides
|
||||
# Redocly CLI guides
|
||||
|
||||
Learn how to work with OpenAPI CLI.
|
||||
Learn how to work with Redocly CLI.
|
||||
|
||||
<div>
|
||||
<Flex justifyContent="space-between" flexWrap="wrap">
|
||||
|
||||
@@ -245,7 +245,7 @@ Be sure to document those options for your users.
|
||||
|
||||
### Different OpenAPI versions
|
||||
|
||||
Redocly OpenAPI CLI supports OpenAPI versions 2.0, 3.0, and 3.1. Most of the time you will use one of them. However, you may need to configure different rules based on the version. You can do that by using additional configuration sections:
|
||||
Redocly CLI supports OpenAPI versions 2.0, 3.0, and 3.1. Most of the time you will use one of them. However, you may need to configure different rules based on the version. You can do that by using additional configuration sections:
|
||||
|
||||
```yaml
|
||||
lint:
|
||||
@@ -277,7 +277,7 @@ Read more about [built-in rules](../resources/built-in-rules.md).
|
||||
|
||||
The OpenAPI specification supports `$refs` in some of the objects. In practice, different tools and implementations of the OAS, as well as API definition authors, may use or even require `$refs` in unsupported places.
|
||||
|
||||
Starting from version `beta-30` onward, OpenAPI CLI automatically resolves all `$refs` by default, even in places where they are not allowed by the specification. This includes primitive values, for example `string`, in description and examples fields.
|
||||
Starting from version `beta-30` onward, Redocly CLI automatically resolves all `$refs` by default, even in places where they are not allowed by the specification. This includes primitive values, for example `string`, in description and examples fields.
|
||||
|
||||
To disable resolving `$refs` in examples, use the `doNotResolveExamples` configuration option in the `lint` section of the Redocly configuration file. This does not affect `$ref` resolution in other parts of the API definition:
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ In this step, you will create a custom plugin and define the decorator dependenc
|
||||
const ReplaceServersURL = require('./decorators/replace-servers-url');
|
||||
const id = 'demo';
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
|
||||
/** @type {import('@redocly/cli').CustomRulesConfig} */
|
||||
const decorators = {
|
||||
oas3: {
|
||||
'replace-servers-url': ReplaceServersURL,
|
||||
@@ -50,7 +50,7 @@ In this step, you will add a decorator and define the environment variable assoc
|
||||
``` JavaScript
|
||||
module.exports = ReplaceServersURL;
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').OasDecorator} */
|
||||
/** @type {import('@redocly/cli').OasDecorator} */
|
||||
|
||||
function ReplaceServersURL() {
|
||||
return {
|
||||
|
||||
@@ -24,7 +24,7 @@ If there are exceptions to the rule, the exceptions can be explicitly added to t
|
||||
## Steps to writing the rule
|
||||
|
||||
1. Identify the type of object to visit. The rules follow the visitor pattern and traverses the tree of the OpenAPI definition.
|
||||
- The [Response](https://github.com/Redocly/openapi-cli/tree/master/packages/core/src/types) object is appropriate because we want to verify the property on the response (not on requests).
|
||||
- The [Response](https://github.com/Redocly/redocly-cli/tree/master/packages/core/src/types) object is appropriate because we want to verify the property on the response (not on requests).
|
||||
1. Find the relationship between the starting object and the property we must evaluate for our decision. (Sometimes this will be the same object as above.)
|
||||
1. Craft the logic for the rule.
|
||||
1. Report the problem.
|
||||
@@ -47,7 +47,7 @@ Based on that, our rule will look like this (before filling in the logic).
|
||||
```js
|
||||
module.exports = ResponseContainsProperty
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').OasRule} */
|
||||
/** @type {import('@redocly/cli').OasRule} */
|
||||
function ResponseContainsProperty (options) {
|
||||
return {
|
||||
Response: {
|
||||
@@ -69,7 +69,7 @@ This sets the default options as `[]`.
|
||||
```js
|
||||
module.exports = ResponseContainsProperty
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').OasRule} */
|
||||
/** @type {import('@redocly/cli').OasRule} */
|
||||
function ResponseContainsProperty (options) {
|
||||
const mustExist = options.mustExist || [];
|
||||
return {
|
||||
@@ -151,7 +151,7 @@ You can copy/paste this to try it out.
|
||||
```js response-contains-property.js
|
||||
module.exports = ResponseContainsProperty
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').OasRule} */
|
||||
/** @type {import('@redocly/cli').OasRule} */
|
||||
function ResponseContainsProperty (options) {
|
||||
const mustExist = options.mustExist || [];
|
||||
return {
|
||||
@@ -185,7 +185,7 @@ function ResponseContainsProperty (options) {
|
||||
const ResponseContainsProperty = require('./rules/response-contains-property');
|
||||
const id = 'demo';
|
||||
|
||||
/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
|
||||
/** @type {import('@redocly/cli').CustomRulesConfig} */
|
||||
const rules = {
|
||||
oas3: {
|
||||
'response-contains-property': ResponseContainsProperty,
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
tocMaxDepth: 2
|
||||
---
|
||||
|
||||
# Redocly OpenAPI CLI
|
||||
# Redocly CLI
|
||||
|
||||
OpenAPI CLI is an open source command-line tool that makes it easier to work with OpenAPI definition files. You can split large files into smaller files, then manage them with your [favorite version control service](../workflows/sources/index.md).
|
||||
Redocly CLI is an open source command-line tool that makes it easier to work with OpenAPI definition files. You can split large files into smaller files, then manage them with your [favorite version control service](../workflows/sources/index.md).
|
||||
|
||||
Commands, rules and plugins help you validate your API definitions and preview docs locally. And when it's time to publish (using Redoc or Redocly, naturally), you can bundle everything back into a single file.
|
||||
|
||||
OpenAPI CLI also integrates with other Redocly products such as the API registry, and you can build production-ready reference docs if you have an enterprise license key.
|
||||
Redocly CLI also integrates with other Redocly products such as the API registry, and you can build production-ready reference docs if you have an enterprise license key.
|
||||
|
||||
## Key features
|
||||
|
||||
@@ -26,16 +26,16 @@ Just because it's open source, doesn't mean we've skimped on the goodies.
|
||||
|
||||
Most customization can be done in the Redocly configuration file (`redocly.yaml`). Create your own [linting rules](./resources/custom-rules.md) to ensure definitions validate to _your_ requirements. Remove content during the bundling process using [decorators](./resources/built-in-decorators.md). Go all out by utilizing plugins and apply a combination of rules and decorators that meet your specific needs.
|
||||
|
||||
## What makes Redocly OpenAPI CLI great
|
||||
## What makes Redocly CLI great
|
||||
|
||||
### Superior performance
|
||||
Unlike other OpenAPI validation tools, Redocly OpenAPI CLI defines the possible type tree of a valid OpenAPI definition, then traverses it (similar to how compilers work). The result? Better performance.
|
||||
Unlike other OpenAPI validation tools, Redocly CLI defines the possible type tree of a valid OpenAPI definition, then traverses it (similar to how compilers work). The result? Better performance.
|
||||
|
||||
### A multi-file approach
|
||||
|
||||
You can write OpenAPI definitions in either a single file or in multiple files. A single file is good for beginners and for simple APIs. The more complex the API, the longer the definition. The longer the definition, the trickier it is to deal with, increasing the risk of syntax and validation errors, and decreasing developer buy-in.
|
||||
|
||||
The solution is a multi-file approach. This is where you define the main structure of the API in a root definition file and everything else is stored in smaller, separate files. During the bundling process, Redocly OpenAPI CLI compiles multiple files (linked with $refs) into one file in a single command. You don't have to install and maintain a third-party tool to do the job.
|
||||
The solution is a multi-file approach. This is where you define the main structure of the API in a root definition file and everything else is stored in smaller, separate files. During the bundling process, Redocly CLI compiles multiple files (linked with $refs) into one file in a single command. You don't have to install and maintain a third-party tool to do the job.
|
||||
|
||||
Compare the examples below. Note that the definitions aren't complete, but they show you what's possible with a multi-file approach.
|
||||
|
||||
@@ -187,11 +187,11 @@ tag:
|
||||
Linting your OpenAPI definition ensures that it's valid and adheres to a set of rules and standards. This is especially important if you follow the design-first approach to developing APIs. You can use built-in linting rules, create your own custom rules — or a combination of both. Custom rules also extend basic functionality so you can respond to specific use-cases.
|
||||
|
||||
## Relationship to Redoc
|
||||
OpenAPI CLI keeps you sane as you maintain your API definitions. [Redoc](../redoc/quickstart.md) swiftly deploys your docs to a website so all your hard work can be appreciated. There are [multiple deployment options for Redoc](../redoc/deployment/intro.md).
|
||||
Redocly CLI keeps you sane as you maintain your API definitions. [Redoc](../redoc/quickstart.md) swiftly deploys your docs to a website so all your hard work can be appreciated. There are [multiple deployment options for Redoc](../redoc/deployment/intro.md).
|
||||
|
||||
## Read the docs!
|
||||
Everything you need to know about Redocly OpenAPI CLI is contained in the following pages. We take as much pride in our docs as we do in our code, so we're always fine-tuning, updating and improving. We suggest you start with our [quickstart guide](./quickstart.md).
|
||||
Everything you need to know about Redocly CLI is contained in the following pages. We take as much pride in our docs as we do in our code, so we're always fine-tuning, updating and improving. We suggest you start with our [quickstart guide](./quickstart.md).
|
||||
|
||||
## Want to contribute?
|
||||
|
||||
Then join our active and supportive community! The source code is available at https://github.com/Redocly/openapi-cli.
|
||||
Then join our active and supportive community! The source code is available at https://github.com/Redocly/redocly-cli.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Install OpenAPI CLI
|
||||
# Install Redocly CLI
|
||||
|
||||
There are two ways to install OpenAPI CLI: global and runtime.
|
||||
There are two ways to install Redocly CLI: global and runtime.
|
||||
|
||||
## Global installation
|
||||
|
||||
@@ -11,11 +11,11 @@ This is the recommended method. Ensure you have the latest version of npm before
|
||||
:::
|
||||
|
||||
```shell Command
|
||||
npm i -g @redocly/openapi-cli@latest
|
||||
npm i -g @redocly/cli@latest
|
||||
```
|
||||
|
||||
```shell Output
|
||||
npm i -g @redocly/openapi-cli@latest
|
||||
npm i -g @redocly/cli@latest
|
||||
added 1 package, removed 1 package, changed 87 packages, and audited 89 packages in 4s
|
||||
found 0 vulnerabilities
|
||||
```
|
||||
@@ -23,29 +23,30 @@ found 0 vulnerabilities
|
||||
### Yarn
|
||||
|
||||
```shell Command
|
||||
yarn global add @redocly/openapi-cli
|
||||
yarn global add @redocly/cli
|
||||
```
|
||||
|
||||
```shell Output
|
||||
yarn global add @redocly/openapi-cli
|
||||
yarn global add @redocly/cli
|
||||
yarn global v1.22.11
|
||||
[1/4] 🔍 Resolving packages...
|
||||
[2/4] 🚚 Fetching packages...
|
||||
[3/4] 🔗 Linking dependencies...
|
||||
[4/4] 🔨 Building fresh packages...
|
||||
|
||||
success Installed "@redocly/openapi-cli@1.0.0-beta.54" with binaries:
|
||||
success Installed "@redocly/cli@1.0.0-beta.95" with binaries:
|
||||
- openapi
|
||||
- redocly
|
||||
✨ Done in 6.90s.
|
||||
```
|
||||
|
||||
### Verify the installation
|
||||
|
||||
Running `openapi --version` will confirm that the installation was successful:
|
||||
Running `redocly --version` will confirm that the installation was successful:
|
||||
|
||||
```shell
|
||||
openapi --version
|
||||
1.0.0-beta.84
|
||||
redocly --version
|
||||
1.0.0-beta.95
|
||||
```
|
||||
|
||||
## Runtime installation
|
||||
@@ -57,15 +58,15 @@ npx is npm's package runner. It will install and run a command at the same time
|
||||
:::
|
||||
|
||||
```shell Command
|
||||
npx @redocly/openapi-cli <command> [options]
|
||||
npx @redocly/cli <command> [options]
|
||||
```
|
||||
|
||||
```shell Example with lint command
|
||||
npx @redocly/openapi-cli@latest lint petstore.yaml
|
||||
npx @redocly/cli@latest lint petstore.yaml
|
||||
```
|
||||
|
||||
```shell Output (lint failed)
|
||||
npx @redocly/openapi-cli@latest lint petstore.yaml
|
||||
npx @redocly/cli@latest lint petstore.yaml
|
||||
No configurations were defined in extends -- using built in recommended configuration by default.
|
||||
|
||||
validating petstore.yaml...
|
||||
@@ -105,7 +106,7 @@ You have 2 warnings.
|
||||
```
|
||||
|
||||
```shell Output (lint succeeded)
|
||||
npx @redocly/openapi-cli@latest lint petstore.yaml
|
||||
npx @redocly/cli@latest lint petstore.yaml
|
||||
No configurations were defined in extends -- using built in recommended configuration by default.
|
||||
|
||||
validating petstore.yaml...
|
||||
@@ -146,7 +147,7 @@ Woohoo! Your OpenAPI definition is valid. 🎉
|
||||
After a successful install, you can set up tab completion for the terminal if you wish. Generate the completion script using the following command:
|
||||
|
||||
```shell Command
|
||||
openapi completion
|
||||
redocly completion
|
||||
```
|
||||
|
||||
```shell Output
|
||||
@@ -190,6 +191,6 @@ The approach is similar for other shells. After the installation, restart your t
|
||||
|
||||
## Next steps
|
||||
|
||||
- Check the full list of [OpenAPI CLI commands](./commands/index.md) available to you
|
||||
- Learn how to fine-tune your OpenAPI CLI tool using a [configuration file](./configuration/index.mdx)
|
||||
- Check the full list of [Redocly CLI commands](./commands/index.md) available to you
|
||||
- Learn how to fine-tune your Redocly CLI tool using a [configuration file](./configuration/index.mdx)
|
||||
- Learn more about [custom plugins and rules](./resources/custom-rules.md)
|
||||
|
||||
@@ -20,7 +20,7 @@ The project is copied to your GitHub account. It is independent and not linked t
|
||||
|
||||
## Step 2: Clone the project
|
||||
|
||||
This step clones the project to your local machine so you can use it with [OpenAPI CLI](quickstart.md).
|
||||
This step clones the project to your local machine so you can use it with [Redocly CLI](quickstart.md).
|
||||
|
||||
### Use GitHub Desktop
|
||||
|
||||
@@ -54,10 +54,10 @@ By default, you will have a root directory (`openapi`) that contains a sample AP
|
||||
|
||||
### Just starting out with API docs?
|
||||
|
||||
Use our `openapi.yaml` file to explore OpenAPI CLI. We suggest you [run some basic commands](quickstart.md) like `lint`, `bundle` and `split` to practice.
|
||||
Use our `openapi.yaml` file to explore Redocly CLI. We suggest you [run some basic commands](quickstart.md) like `lint`, `bundle` and `split` to practice.
|
||||
|
||||
### Got your own API definition file?
|
||||
|
||||
You can add your files straight into the `openapi` folder and use the existing sub-folders when splitting them up for easier maintenance (`split` command) and compiling them back into a single file (`bundle`) for publishing out. Be aware that the more definitions stored in the `openapi` folder, the more cluttered the sub-folders. But hey, if you like clutter then go for it!
|
||||
|
||||
Prefer things more orderly? Create new root folders to store each definition. When you run the `split` command in OpenAPI CLI for a specified definition file, the sub-folders will automatically be created under the root and populated with the constituent parts of your main definition file.
|
||||
Prefer things more orderly? Create new root folders to store each definition. When you run the `split` command in Redocly CLI for a specified definition file, the sub-folders will automatically be created under the root and populated with the constituent parts of your main definition file.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Redocly OpenAPI CLI quickstart guide
|
||||
# Redocly CLI quickstart guide
|
||||
|
||||
## Before you begin
|
||||
|
||||
@@ -7,23 +7,23 @@
|
||||
|
||||
## Step 1 - Clone the openapi-starter project
|
||||
|
||||
[openapi-starter](https://github.com/Redocly/openapi-starter) creates a local folder structure that you can use to manage your API definition either as a single file, or in multi-file format. It also places a basic API definition file called `openapi.yaml` in the `openapi` root folder for those of you who don't have a definition file but need one to start exploring OpenAPI CLI. You're welcome!
|
||||
[openapi-starter](https://github.com/Redocly/openapi-starter) creates a local folder structure that you can use to manage your API definition either as a single file, or in multi-file format. It also places a basic API definition file called `openapi.yaml` in the `openapi` root folder for those of you who don't have a definition file but need one to start exploring Redocly CLI. You're welcome!
|
||||
|
||||
If you have your own definition file, go right ahead and use it.
|
||||
|
||||
If you want to learn how to clone the `openapi-starter` project and see how it works, we have [an entire page dedicated to it](openapi-starter.md)!
|
||||
|
||||
## Step 2 - Install OpenAPI CLI from openapi-starter
|
||||
## Step 2 - Install Redocly CLI from openapi-starter
|
||||
|
||||
Run `npm install` in the root of your local `openapi-starter` project.
|
||||
|
||||
## Step 3 - Prepare your API definition file
|
||||
|
||||
In this guide, we'll use `openapi.yaml` from the `openapi-starter` project in all examples. We recommend that you use it until you're confident with OpenAPI CLI.
|
||||
In this guide, we'll use `openapi.yaml` from the `openapi-starter` project in all examples. We recommend that you use it until you're confident with Redocly CLI.
|
||||
|
||||
## Step 4 - Try some basic commands
|
||||
|
||||
[OpenAPI CLI commands](./commands/index.md) are used to run tasks (like splitting up large definition files and putting them back together) and they can also return information (like getting stats about your definition). To get you started, we'll focus on the top four: `bundle`, `lint`, `split` and `preview`.
|
||||
[Redocly CLI commands](./commands/index.md) are used to run tasks (like splitting up large definition files and putting them back together) and they can also return information (like getting stats about your definition). To get you started, we'll focus on the top four: `bundle`, `lint`, `split` and `preview`.
|
||||
|
||||
:::success Tip
|
||||
If you're new to command-line interfaces, note that you don't have to include the `$` in your commands. This symbol only indicates that the command after it should be entered into the terminal. To run a command, open your terminal, use `cd` to access the path where your API definition file is stored, type the command, and press **Enter**.
|
||||
@@ -109,7 +109,7 @@ bundled.yaml: validated in 72ms
|
||||
run `openapi lint --generate-ignore-file` to add all problems to the ignore file.
|
||||
```
|
||||
|
||||
You got this response because `lint` uses rules to ensure that your file conforms to what you consider to be 'valid'. OpenAPI CLI ships with a set of built-in rules, but you can also customise your own, depending on how closely you want to follow the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html). In our example response above, we can see that there is one error [1] and one warning [2].
|
||||
You got this response because `lint` uses rules to ensure that your file conforms to what you consider to be 'valid'. Redocly CLI ships with a set of built-in rules, but you can also customise your own, depending on how closely you want to follow the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html). In our example response above, we can see that there is one error [1] and one warning [2].
|
||||
|
||||
**Why you got an error**
|
||||
|
||||
@@ -192,7 +192,7 @@ So, what just happened? Take a look in the newly created `bundled` directory. Th
|
||||
|
||||
:::info Note
|
||||
|
||||
`openapi.yaml` in the `bundled` folder is the default name that OpenAPI CLI gives to the 'root' YAML file you just split up. It contains `$ref`s to its constituent parts. You do the work in the constituent parts.
|
||||
`openapi.yaml` in the `bundled` folder is the default name that Redocly CLI gives to the 'root' YAML file you just split up. It contains `$ref`s to its constituent parts. You do the work in the constituent parts.
|
||||
|
||||
:::
|
||||
|
||||
@@ -217,7 +217,7 @@ You should get this response:
|
||||
|
||||
```bash
|
||||
Using Redoc community edition.
|
||||
Login with openapi-cli login or use an enterprise license key to preview with the premium docs.
|
||||
Login with `redocly login` or use an enterprise license key to preview with the premium docs.
|
||||
|
||||
🔎 Preview server running at http://127.0.0.1:8080
|
||||
|
||||
@@ -259,6 +259,6 @@ Back in `http://127.0.0.1:8080` the update will be visible.
|
||||
|
||||
## Now, get into it!
|
||||
|
||||
* Take a look at [all of the available OpenAPI CLI commands](./commands/index.md).
|
||||
* Fine-tune OpenAPI CLI through the awesome magic that is the [config file](./configuration/index.mdx).
|
||||
* Take a look at [all of the available Redocly CLI commands](./commands/index.md).
|
||||
* Fine-tune Redocly CLI through the awesome magic that is the [config file](./configuration/index.mdx).
|
||||
* Get creative and head straight to [custom plugins and rules](./resources/custom-rules.md).
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
title: Built-in decorators in OpenAPI CLI
|
||||
title: Built-in decorators in Redocly CLI
|
||||
---
|
||||
|
||||
# Built-in decorators
|
||||
|
||||
Decorators are used to modify content in API definitions during the bundle process, after the validation is complete. Redocly supports several built-in decorators that you can use with OpenAPI CLI.
|
||||
Decorators are used to modify content in API definitions during the bundle process, after the validation is complete. Redocly supports several built-in decorators that you can use with Redocly CLI.
|
||||
|
||||
To use any of the decorators listed on this page, configure them in the `lint.decorators` section of the Redocly configuration file in your working directory.
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Built-in rules in OpenAPI CLI
|
||||
title: Built-in rules in Redocly CLI
|
||||
redirectFrom:
|
||||
- /docs/cli/built-in-rules/
|
||||
---
|
||||
|
||||
# Built-in rules
|
||||
|
||||
All of our built-in OpenAPI CLI rules are listed on this page.
|
||||
All of our built-in Redocly CLI rules are listed on this page.
|
||||
We don't ship any built-in preprocessors.
|
||||
|
||||
To change your settings for any given rule, add or modify its corresponding entry in the `lint.rules` section of the Redocly configuration file in your working directory.
|
||||
@@ -400,5 +400,5 @@ Here is the equivalent of the `recommended` configuration values:
|
||||
|
||||
## Built-in rule ideas
|
||||
|
||||
OpenAPI-cli supports [custom rules](./custom-rules.md).
|
||||
However, if you have an idea for a built-in rule you believe will benefit the greater API community, please [open an issue](https://github.com/Redocly/openapi-cli/issues/new) in the OpenAPI CLI repository.
|
||||
Redocly CLI supports [custom rules](./custom-rules.md).
|
||||
However, if you have an idea for a built-in rule you believe will benefit the greater API community, please [open an issue](https://github.com/Redocly/redocly-cli/issues/new) in the Redocly CLI repository.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Custom plugins and rules in OpenAPI CLI
|
||||
title: Custom plugins and rules in Redocly CLI
|
||||
redirectFrom:
|
||||
- /docs/cli/custom-rules/
|
||||
---
|
||||
@@ -61,7 +61,7 @@ Some examples:
|
||||
|
||||
# Custom rules
|
||||
|
||||
Each rule is a function that accepts rule config and returns an object with methods that openapi-cli calls to "visit" nodes while traversing the definition document.
|
||||
Each rule is a function that accepts rule config and returns an object with methods that Redocly CLI calls to "visit" nodes while traversing the definition document.
|
||||
|
||||
Here is the basic example of a rule:
|
||||
|
||||
@@ -88,9 +88,9 @@ See an example of a custom rule implementation in our ["Response contains proper
|
||||
Keys of the object can be any of the following:
|
||||
|
||||
- node type - visitor will be called on specific node type. List of available node types for each specific OAS version:
|
||||
- OAS 3.1: https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3_1.ts#L209
|
||||
- OAS 3.0: https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3.ts#L530
|
||||
- OAS 2.0: https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas2.ts#L367
|
||||
- OAS 3.1: https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/types/oas3_1.ts#L209
|
||||
- OAS 3.0: https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/types/oas3.ts#L530
|
||||
- OAS 2.0: https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/types/oas2.ts#L367
|
||||
- `any` - visitor will be called on every node
|
||||
- `ref` - visitor will be called on $ref nodes
|
||||
|
||||
@@ -99,7 +99,7 @@ The value of each node can be either **visitor function** (runs while going down
|
||||
## Visitor object
|
||||
Visitor object can contain `enter` and/or `leave` visitor functions and `skip` predicate method.
|
||||
|
||||
`openapi-cli` calls `enter` **visitor function** while going down the tree and `leave` going up the tree.
|
||||
Redocly CLI calls `enter` **visitor function** while going down the tree and `leave` going up the tree.
|
||||
`skip` predicate is called and if it returns `true` the node is ignored for this visitor.
|
||||
|
||||
|
||||
@@ -148,7 +148,7 @@ function ExampleRule() {
|
||||
}
|
||||
```
|
||||
|
||||
The `Schema` **visitor function** will be called by openapi-cli if only Schema Object is encountered while traversing a tree while the Operation Object is **entered**.
|
||||
The `Schema` **visitor function** will be called by Redocly CLI if only Schema Object is encountered while traversing a tree while the Operation Object is **entered**.
|
||||
|
||||
As the third argument, the **visitor function** accepts the `parents` object with corresponding parent nodes as defined in the **visitor object**.
|
||||
|
||||
@@ -242,7 +242,7 @@ By default, the message is reported at the current node location.
|
||||
|
||||
# Custom plugins
|
||||
|
||||
Plugins can be used to extend behavior of `@redocly/openapi-cli`.
|
||||
Plugins can be used to extend behavior of `@redocly/cli`.
|
||||
Each plugin is a JavaScript module which can export custom rules, preprocessors, decorators or type tree extensions.
|
||||
|
||||
## Plugin structure
|
||||
@@ -259,11 +259,11 @@ module.exports = {
|
||||
|
||||
Everything that is exported from plugin can be related to one of supported OAS major versions. It is done by exporting object containing key-value mapping from major OAS version (`oas2` or `oas3` are supported) to the extension object (rules, preprocessors, decorators).
|
||||
|
||||
Before processing the definition document openapi-cli detects the OAS version and applies corresponding set of extensions.
|
||||
Before processing the definition document Redocly CLI detects the OAS version and applies corresponding set of extensions.
|
||||
|
||||
## Rules in plugins
|
||||
|
||||
Plugins can expose additional rules for use in openapi-cli.
|
||||
Plugins can expose additional rules for use in Redocly CLI.
|
||||
To do so, the plugin must export a `rules` object containing a key-value mapping of rule ID to rule.
|
||||
The rule ID does not have to follow any naming convention (so it can be `tag-name`, for instance).
|
||||
Sample rules definition:
|
||||
@@ -282,7 +282,7 @@ module.exports = {
|
||||
}
|
||||
```
|
||||
|
||||
To use the rule in openapi-cli, you would use the plugin name, followed by a slash, followed by the rule name.
|
||||
To use the rule in Redocly CLI, you would use the plugin name, followed by a slash, followed by the rule name.
|
||||
So if this plugin id is `my-local-plugin`, then in your configuration you'd refer to the rule by the name `my-local-plugin/tag-name`.
|
||||
Example: `"rules": {"my-local-plugin/tag-name": "error"}`.
|
||||
|
||||
@@ -376,8 +376,8 @@ Community plugins are not supported yet.
|
||||
|
||||
## Type definitions
|
||||
|
||||
`openapi-cli` in its core has a type tree which defines the structure of the OpenAPI definition.
|
||||
`openapi-cli` then uses it to do type-aware traversal of OpenAPI Document.
|
||||
Redocly CLI in its core has a type tree which defines the structure of the OpenAPI definition.
|
||||
Redocly CLI then uses it to do type-aware traversal of OpenAPI Document.
|
||||
|
||||
The type tree is built from top level `Types` which can link to child types.
|
||||
|
||||
|
||||
@@ -1,22 +1,22 @@
|
||||
---
|
||||
title: OpenAPI CLI resources
|
||||
description: Learn more about how OpenAPI CLI works
|
||||
title: Redocly CLI resources
|
||||
description: Learn more about how Redocly CLI works
|
||||
---
|
||||
|
||||
import { WideTile, Flex } from '@redocly/developer-portal/ui';
|
||||
|
||||
# OpenAPI CLI resources
|
||||
# Redocly CLI resources
|
||||
|
||||
Additional information on concepts, features, and functionalities related to OpenAPI CLI.
|
||||
Additional information on concepts, features, and functionalities related to Redocly CLI.
|
||||
|
||||
<div>
|
||||
|
||||
<Flex justifyContent="space-between" flexWrap="wrap">
|
||||
<WideTile to="./built-in-rules.md" header="Built-in lint rules">
|
||||
List of lint rules provided with OpenAPI CLI
|
||||
List of lint rules provided with Redocly CLI
|
||||
</WideTile>
|
||||
<WideTile to="./built-in-decorators.md" header="Built-in decorators">
|
||||
List of decorators provided with OpenAPI CLI
|
||||
List of decorators provided with Redocly CLI
|
||||
</WideTile>
|
||||
<WideTile to="./custom-rules.md" header="Custom plugins and rules">
|
||||
Guidelines for writing your own plugins and rules
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
:::warning Warning
|
||||
|
||||
The assertions syntax is [under construction](https://github.com/Redocly/openapi-cli/issues/647).
|
||||
The assertions syntax is [under construction](https://github.com/Redocly/redocly-cli/issues/647).
|
||||
Follow or comment in the issue for more details.
|
||||
|
||||
:::
|
||||
@@ -421,7 +421,7 @@ lint:
|
||||
severity: error
|
||||
maxLength: 20
|
||||
```
|
||||
|
||||
Redocly CLI
|
||||
## OpenAPI node types
|
||||
|
||||
Redocly defines a type tree based on the document type.
|
||||
@@ -430,10 +430,10 @@ OpenAPI 3.0 and OpenAPI 3.1 share a type tree.
|
||||
|
||||
### List of OpenAPI types
|
||||
|
||||
For technical details on the implementation of types for each OAS version, consult the source files in the OpenAPI CLI repository:
|
||||
- OAS 3.1: https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3_1.ts#L209
|
||||
- OAS 3.0: https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3.ts#L530
|
||||
- OAS 2.0: https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas2.ts#L367
|
||||
For technical details on the implementation of types for each OAS version, consult the source files in the Redocly CLI repository:
|
||||
- OAS 3.1: https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/types/oas3_1.ts#L209
|
||||
- OAS 3.0: https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/types/oas3.ts#L530
|
||||
- OAS 2.0: https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/types/oas2.ts#L367
|
||||
|
||||
List of types for OpenAPI 3.0 and 3.1:
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 3.5 MiB After Width: | Height: | Size: 3.5 MiB |
13
package-lock.json
generated
13
package-lock.json
generated
@@ -1,11 +1,11 @@
|
||||
{
|
||||
"name": "@redocly/openapi",
|
||||
"name": "@redocly/cli",
|
||||
"version": "1.0.0-beta.95",
|
||||
"lockfileVersion": 2,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@redocly/openapi",
|
||||
"name": "@redocly/cli",
|
||||
"version": "1.0.0-beta.95",
|
||||
"license": "MIT",
|
||||
"workspaces": [
|
||||
@@ -916,7 +916,7 @@
|
||||
"url": "https://github.com/sponsors/epoberezkin"
|
||||
}
|
||||
},
|
||||
"node_modules/@redocly/openapi-cli": {
|
||||
"node_modules/@redocly/cli": {
|
||||
"resolved": "packages/cli",
|
||||
"link": true
|
||||
},
|
||||
@@ -10121,7 +10121,7 @@
|
||||
}
|
||||
},
|
||||
"packages/cli": {
|
||||
"name": "@redocly/openapi-cli",
|
||||
"name": "@redocly/cli",
|
||||
"version": "1.0.0-beta.95",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
@@ -10138,7 +10138,8 @@
|
||||
"yargs": "17.0.1"
|
||||
},
|
||||
"bin": {
|
||||
"openapi": "bin/cli.js"
|
||||
"openapi": "bin/cli.js",
|
||||
"redocly": "bin/cli.js"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/yargs": "16.0.2",
|
||||
@@ -10891,7 +10892,7 @@
|
||||
"uri-js": "^4.2.2"
|
||||
}
|
||||
},
|
||||
"@redocly/openapi-cli": {
|
||||
"@redocly/cli": {
|
||||
"version": "file:packages/cli",
|
||||
"requires": {
|
||||
"@redocly/openapi-core": "1.0.0-beta.95",
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "@redocly/openapi",
|
||||
"name": "@redocly/cli",
|
||||
"version": "1.0.0-beta.95",
|
||||
"description": "",
|
||||
"private": true,
|
||||
@@ -33,7 +33,7 @@
|
||||
],
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/Redocly/openapi-cli.git"
|
||||
"url": "https://github.com/Redocly/redocly-cli.git"
|
||||
},
|
||||
"keywords": [
|
||||
"linter",
|
||||
|
||||
@@ -1,16 +1,15 @@
|
||||
# OpenAPI CLI toolset
|
||||
# Redocly CLI toolset
|
||||
|
||||
OpenAPI CLI toolbox with rich validation and bundling features.
|
||||
Redocly CLI toolbox with rich validation and bundling features.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
Currently, @redocly/openapi-cli supports these features:
|
||||
Currently, @redocly/cli supports these features:
|
||||
|
||||
- [x] Multifile validation. No need to bundle your file before validation.
|
||||
- [x] Lightning-fast validation. Lint a 1 Mb file in less than one second.
|
||||
@@ -23,15 +22,15 @@ Currently, @redocly/openapi-cli supports these features:
|
||||
- [x] Decorators to modify a validated definition during bundling.
|
||||
- [x] Preview reference docs for local development.
|
||||
- [x] Support for OpenAPI 2 (fka Swagger) and OpenAPI 3.0.
|
||||
- [ ] Support for OpenAPI 3.1 ([coming soon](https://github.com/Redocly/openapi-cli/issues/160)).
|
||||
- [ ] Support for OpenAPI 3.1 ([coming soon](https://github.com/Redocly/redocly-cli/issues/160)).
|
||||
|
||||
## What makes this tool different
|
||||
|
||||
Unlike other OpenAPI linters, `@redocly/openapi-cli` defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how linters for programming languages work and results in major performance benefits over other approaches. Extend functionality at different points in the lifecycle with preprocessors, rules, and decorators.
|
||||
Unlike other OpenAPI linters, `@redocly/cli` defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how linters for programming languages work and results in major performance benefits over other approaches. Extend functionality at different points in the lifecycle with preprocessors, rules, and decorators.
|
||||
|
||||
## TLDR
|
||||
|
||||
`npx @redocly/openapi-cli lint path-to-root-file.yaml`
|
||||
`npx @redocly/cli lint path-to-root-file.yaml`
|
||||
|
||||
## [Read the docs](https://redoc.ly/docs/cli/)
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
{
|
||||
"name": "@redocly/openapi-cli",
|
||||
"name": "@redocly/cli",
|
||||
"version": "1.0.0-beta.95",
|
||||
"description": "",
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"openapi": "bin/cli.js"
|
||||
"openapi": "bin/cli.js",
|
||||
"redocly": "bin/cli.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=12.0.0"
|
||||
@@ -17,9 +18,9 @@
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/Redocly/openapi-cli.git"
|
||||
"url": "https://github.com/Redocly/redocly-cli.git"
|
||||
},
|
||||
"homepage": "https://github.com/Redocly/openapi-cli",
|
||||
"homepage": "https://github.com/Redocly/redocly-cli",
|
||||
"keywords": [
|
||||
"linter",
|
||||
"OpenAPI",
|
||||
|
||||
@@ -86,7 +86,7 @@ export async function previewDocs(argv: {
|
||||
const isAuthorized = isAuthorizedWithRedocly || redocOptions.licenseKey;
|
||||
if (!isAuthorized) {
|
||||
process.stderr.write(
|
||||
`Using Redoc community edition.\nLogin with openapi-cli ${colorette.blue(
|
||||
`Using Redoc community edition.\nLogin with redocly ${colorette.blue(
|
||||
'login',
|
||||
)} or use an enterprise license key to preview with the premium docs.\n\n`,
|
||||
);
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# openapi-core
|
||||
|
||||
See https://github.com/Redocly/openapi-cli
|
||||
See https://github.com/Redocly/redocly-cli
|
||||
|
||||
## Basic usage
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/Redocly/openapi-cli.git"
|
||||
"url": "https://github.com/Redocly/redocly-cli.git"
|
||||
},
|
||||
"browser": {
|
||||
"fs": false,
|
||||
@@ -18,7 +18,7 @@
|
||||
"os": false,
|
||||
"node-fetch": false
|
||||
},
|
||||
"homepage": "https://github.com/Redocly/openapi-cli",
|
||||
"homepage": "https://github.com/Redocly/redocly-cli",
|
||||
"keywords": [
|
||||
"linter",
|
||||
"OpenAPI",
|
||||
|
||||
@@ -29,7 +29,7 @@ function prepareRevision(revision) {
|
||||
|
||||
// Returns the complete git hash for a given git revision reference.
|
||||
const hash = exec(`git rev-parse "${revision}"`);
|
||||
const dir = path.join(os.tmpdir(), 'openapi-cli-benchmark', hash);
|
||||
const dir = path.join(os.tmpdir(), 'redocly-cli-benchmark', hash);
|
||||
if (fs.existsSync(dir)) {
|
||||
fs.rmdirSync(dir, { recursive: true});
|
||||
}
|
||||
|
||||
@@ -71,7 +71,7 @@ export class RedoclyClient {
|
||||
process.stderr.write(
|
||||
`${yellow(
|
||||
'Warning:',
|
||||
)} invalid Redocly API key. Use "npx @redocly/openapi-cli login" to provide your API key\n`,
|
||||
)} invalid Redocly API key. Use "npx @redocly/cli login" to provide your API key\n`,
|
||||
);
|
||||
return undefined;
|
||||
}
|
||||
|
||||
@@ -7,7 +7,7 @@ export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
|
||||
|
||||
// As 'Assertions' has an array of asserts,
|
||||
// that array spreads into an 'opts' object on init rules phase here
|
||||
// https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/config/config.ts#L311
|
||||
// https://github.com/Redocly/redocly-cli/blob/master/packages/core/src/config/config.ts#L311
|
||||
// that is why we need to iterate through 'opts' values;
|
||||
// before - filter only object 'opts' values
|
||||
const assertions: any[] = Object.values(opts).filter(
|
||||
|
||||
Reference in New Issue
Block a user