mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-06 20:57:44 +00:00
76669ca2ab
* Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * Update quickstart.md * docs: minor formatting and copyedit updates * docs: Update final example and add closing links * docs: fix a markdown issue * docs: run prettier --------- Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>
118 lines
4.7 KiB
Markdown
118 lines
4.7 KiB
Markdown
# Redocly CLI quickstart guide
|
|
|
|
Take your first steps with the Redocly CLI by following the steps in this guide.
|
|
|
|
Before you start:
|
|
|
|
- [Install the Redocly CLI](./installation.md) if you haven't already
|
|
- Create a new project folder and `cd` into the folder
|
|
- If you have an OpenAPI description to use, copy it into your project (we assume it's called `openapi.yaml`), or [try our example](https://github.com/Redocly/openapi-starter/blob/main/openapi/openapi.yaml)
|
|
|
|
{% admonition type="attention" %}
|
|
There's also an [openapi-starter](https://github.com/Redocly/openapi-starter) repository that you can clone and experiment with to get your bearings
|
|
{% /admonition %}
|
|
|
|
## Preview API documentation
|
|
|
|
Redocly CLI has support for showing a preview of [Redoc](https://redocly.com/redoc/) rendering your API docs, which updates when the API description updates.
|
|
Run the command:
|
|
|
|
```bash
|
|
redocly preview-docs openapi.yaml
|
|
```
|
|
|
|
The `redocly preview-docs` command triggers the creation of the doc preview for your API descriptions on your local machine. Once the doc preview has been generated, a url is printed as output to the CLI, as seen in the example below.
|
|
|
|
The API Doc preview takes a few moments to build. Upon completion, it provides the host and port where the preview server runs - typically `http://localhost:8080`.
|
|
|
|
<details><summary>Preview-docs command output</summary>
|
|
|
|
```text
|
|
Using Redoc community edition.
|
|
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
|
|
|
|
👀 Watching openapi-starter/openapi/openapi.yaml and all related resources for changes
|
|
|
|
|
|
Bundling...
|
|
|
|
Created a bundle for openapi-starter/openapi/openapi.yaml successfully
|
|
GET /: 18.123ms
|
|
GET /simplewebsocket.min.js: 4.256ms
|
|
GET /hot.js: 4.765ms
|
|
GET /openapi.json: 1.73ms
|
|
GET /favicon.ico: 1.556ms
|
|
```
|
|
|
|
</details>
|
|
|
|
Open that URL in your browser, and admire your lovely API documentation!
|
|
|
|
|
|
|
|
## Lint an OpenAPI description
|
|
|
|
Linting helps create consistent API descriptions and helps you avoid bugs, leading to a smoother developer experience. Using linting as part of your API workflow optimizes maintainability, facilitates ease of onboarding, and increases the adoption of the API.
|
|
|
|
The `lint` command is used to check that the OpenAPI description is compliant with a set of rules. To get started using a default ruleset, try the following command:
|
|
|
|
```bash
|
|
redocly lint --extends minimal openapi.yaml
|
|
```
|
|
|
|
The command uses a [minimal ruleset](./rules/minimal.md) to lint the API description, and outputs a report of whether the API met the expected standard, as shown in the following example:
|
|
|
|
```text
|
|
validating openapi-starter/openapi/openapi.yaml...
|
|
[1] openapi-starter/openapi/openapi.yaml:72:10 at #/servers/1/url
|
|
|
|
Server `url` should not point to example.com or localhost.
|
|
|
|
70 | default: www
|
|
71 | description: Your tenant id
|
|
72 | - url: https://example.com/api/v1
|
|
73 | paths:
|
|
74 | '/users/{username}':
|
|
|
|
Warning was generated by the no-server-example.com rule.
|
|
|
|
|
|
openapi-starter/openapi/openapi.yaml: validated in 109ms
|
|
|
|
Woohoo! Your API description is valid. 🎉
|
|
You have 1 warning.
|
|
```
|
|
|
|
The output shows any aspects where the OpenAPI doesn't meet the standard. If you get too much output, try adding the `--format summary` parameter to the command.
|
|
|
|
Feeling brave and highly API compliant? Try the `recommended` standard instead and see how yours measures up.
|
|
|
|
## Craft a custom ruleset
|
|
|
|
Redocly CLI has some [great built-in rules](./rules/built-in-rules.md), and you can use these to build up a ruleset that works for you.
|
|
|
|
For example, let's build a lightweight ruleset using the [minimal ruleset](./rules/minimal.md) and adding some built-in rules to create a custom ruleset. You can see an example in the following snippet:
|
|
|
|
```yaml
|
|
extends:
|
|
- minimal
|
|
|
|
rules:
|
|
path-parameters-defined: error
|
|
operation-operationId: error
|
|
paths-kebab-case: warn
|
|
```
|
|
|
|
By taking the existing ruleset and adding some rule configuration, we can alter the rules and make a ruleset that suits our use case. Use this example as a starting point and then iterate to create a configuration that fits your needs.
|
|
|
|
## Next steps
|
|
|
|
After this quick tour of Redocly CLI, you can spend more time in the areas that interest you. Try one of the following:
|
|
|
|
- Check the [list of CLI commands](./commands/index.md) to find out what else you can do and get more information about each command.
|
|
- Add some [configurable rules](./rules/configurable-rules.md) to your setup for anything you need that doesn't have a built-in rule.
|
|
- [Use Redocly CLI with GitHub Actions](https://redocly.com/blog/consistent-apis-redocly-github-actions) for repeatably awesome API governance.
|