@redocly/cli 1.0.0-rc.1 → 1.0.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +100 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Redocly CLI
|
|
2
|
+
|
|
3
|
+
Command-line utility from [@Redocly](https://redocly.com) with OpenAPI superpowers. Build, manage and quality-check OpenAPI descriptions, configure and execute API governance, and publish beautiful API documentation. Supports OpenAPI 3.1, 3.0 and OpenAPI 2.0 (legacy Swagger format).
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
### Node
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
npx @redocly/cli lint path-to-root-file.yaml
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Alternatively, install it globally with `npm`:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
npm install @redocly/cli -g
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Then you can use it as `redocly [command] [options]`, for example:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
redocly lint path-to-root-file.yaml
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Docker
|
|
32
|
+
|
|
33
|
+
To give the Docker container access to the OpenAPI definition files, you need to
|
|
34
|
+
mount the containing directory as a volume. Assuming the OAS definition is rooted
|
|
35
|
+
in the current working directory, you need the following command:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
To build and run with a local image, run the following from the project root:
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
docker build -t redocly/cli .
|
|
45
|
+
docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Common tasks
|
|
49
|
+
|
|
50
|
+
### Generate API reference documentation
|
|
51
|
+
|
|
52
|
+
Redocly CLI is a great way to render API reference documentation. It uses open source [Redoc](https://github.com/redocly/redoc) to build your documentation. Use a command like this:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
redocly build-docs openapi.yaml
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Your API reference docs are in `redoc-static.html` by default. You can customize this in many ways. [Read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information.
|
|
59
|
+
|
|
60
|
+
> :bulb: Redocly also has [hosted API reference docs](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/), a (commercial) alternative to Redoc. Both Redoc and Redocly API reference docs can be worked on locally using the `preview-docs` command.
|
|
61
|
+
|
|
62
|
+
### Lint an API description against a standard
|
|
63
|
+
|
|
64
|
+
Check your API meets the expected standards using `lint` to ensure quality in every version of your API. Our API linter is designed for speed on even large documents, so it's easy to run locally, in CI, or anywhere you need it. It's also designed for humans, with meaningful error messages to help you get your API right every time. Try it like this:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
redocly lint openapi.yaml
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Configure the rules** as you wish. No JSONPath here, just type-aware expressions that understand the OpenAPI structure. You can either use the [built-in rules](https://redocly.com/docs/cli/rules) to mix-and-match your ideal API standard, or break out the tools to build your own.
|
|
71
|
+
|
|
72
|
+
**Format the output** in whatever way you need, the `stylish` output is as good as it sounds, but if you need JSON or Checkstyle outputs to integrate with other tools, we've got those too.
|
|
73
|
+
|
|
74
|
+
**Multiple files supported** so you don't need to bundle your API description to lint it, just give the entry point and Redocly CLI does the rest.
|
|
75
|
+
|
|
76
|
+
[Learn more about API standards and configuring Redocly rules](https://redocly.com/docs/cli/api-standards).
|
|
77
|
+
|
|
78
|
+
### Transform an OpenAPI description
|
|
79
|
+
|
|
80
|
+
If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly [decorators](https://redocly.com/docs/cli/decorators) feature. This allows you to:
|
|
81
|
+
|
|
82
|
+
- Publish reference docs with a subset of endpoints for public use
|
|
83
|
+
- Improve the docs by adding examples and descriptions
|
|
84
|
+
- Adapt an existing OpenAPI description, and replace details like URLs for use on staging platforms
|
|
85
|
+
|
|
86
|
+
## Data collection
|
|
87
|
+
|
|
88
|
+
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`.
|
|
89
|
+
|
|
90
|
+
## More resources
|
|
91
|
+
|
|
92
|
+
[Read the detailed docs](https://redocly.com/docs/cli/).
|
|
93
|
+
|
|
94
|
+
## Credits
|
|
95
|
+
|
|
96
|
+
Thanks to [graphql-js](https://github.com/graphql/graphql-js) and [eslint](https://github.com/eslint/eslint) for inspiration of the definition traversal approach and to [Swagger](https://github.com/swagger-api/swagger-editor), [Spectral](https://github.com/stoplightio/spectral), and [OAS-Kit](https://github.com/Mermade/oas-kit) for inspiring the recommended ruleset.
|
|
97
|
+
|
|
98
|
+
## Development
|
|
99
|
+
|
|
100
|
+
Contributions are welcome! All the information you need is in [CONTRIBUTING.md](.github/CONTRIBUTING.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@redocly/cli",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.2",
|
|
4
4
|
"description": "",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"engineStrict": true,
|
|
14
14
|
"scripts": {
|
|
15
15
|
"compile": "tsc",
|
|
16
|
-
"copy-assets": "cp src/commands/preview-docs/preview-server/default.hbs lib/commands/preview-docs/preview-server/default.hbs && cp src/commands/preview-docs/preview-server/hot.js lib/commands/preview-docs/preview-server/hot.js && cp src/commands/preview-docs/preview-server/oauth2-redirect.html lib/commands/preview-docs/preview-server/oauth2-redirect.html && cp src/commands/build-docs/template.hbs lib/commands/build-docs/template.hbs",
|
|
16
|
+
"copy-assets": "cp src/commands/preview-docs/preview-server/default.hbs lib/commands/preview-docs/preview-server/default.hbs && cp src/commands/preview-docs/preview-server/hot.js lib/commands/preview-docs/preview-server/hot.js && cp src/commands/preview-docs/preview-server/oauth2-redirect.html lib/commands/preview-docs/preview-server/oauth2-redirect.html && cp src/commands/build-docs/template.hbs lib/commands/build-docs/template.hbs && cp ../../README.md .",
|
|
17
17
|
"prepack": "npm run copy-assets",
|
|
18
18
|
"prepublishOnly": "npm run copy-assets"
|
|
19
19
|
},
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"Roman Hotsiy <roman@redoc.ly> (https://redoc.ly/)"
|
|
35
35
|
],
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@redocly/openapi-core": "1.0.0-rc.
|
|
37
|
+
"@redocly/openapi-core": "1.0.0-rc.2",
|
|
38
38
|
"assert-node-version": "^1.0.3",
|
|
39
39
|
"chokidar": "^3.5.1",
|
|
40
40
|
"colorette": "^1.2.0",
|