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

refactor: rename to API description for consistency (#1239)

Browse Source
This commit is contained in:
Adam Altman
2023-09-18 08:22:26 -05:00
committed by GitHub
parent 680c431cbb
commit 0a73f1f557
129 changed files with 273 additions and 282 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.changeset/three-moose-cheer.md Normal file
View File

@@ -0,0 +1,6 @@
---
'@redocly/openapi-core': patch
'@redocly/cli': patch
---
Renamed API definition to API description for consistency.

2
.github/CONTRIBUTING.md vendored
View File

@@ -194,7 +194,7 @@ E2E tests are sensitive to any additional output (like `console.log`) in the sou
- **`packages/core/src/types`**: contains the common types for several OpenAPI versions.
- **`packages/core/src/typings`**: contains the common Typescript typings.
- **`resources`**: contains some example API definitions and configuration files that might be useful for testing.
- **`resources`**: contains some example API descriptions and configuration files that might be useful for testing.
## Release flow

4
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -26,9 +26,9 @@ Steps to reproduce the behavior:
<!-- If applicable, add logs to help explain your problem. -->
**OpenAPI definition**
**OpenAPI description**
<!-- If applicable, add an OpenAPI definition and `.redocly.yaml` configuration file that helps reproduce the problem.
<!-- If applicable, add an OpenAPI description 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). -->
**Redocly Version(s)**

1
.github/styles/Vocab/Rules/accept.txt vendored
View File

@@ -124,6 +124,7 @@ OpenTracing
Operator
OperatorHub
OpenAPI
AsyncAPI
osd
PHP
PostgreSQL

6
README.md
View File

@@ -30,8 +30,8 @@ redocly lint path-to-root-file.yaml
### Docker
To give the Docker container access to the OpenAPI definition files, you need to
mount the containing directory as a volume. Assuming the OAS definition is rooted
To give the Docker container access to the OpenAPI description files, you need to
mount the containing directory as a volume. Assuming the API description is rooted
in the current working directory, you need the following command:
```
@@ -93,7 +93,7 @@ This tool [collects data](./docs/usage-data.md) to help Redocly improve our prod
## Credits
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.
Thanks to [graphql-js](https://github.com/graphql/graphql-js) and [eslint](https://github.com/eslint/eslint) for inspiration of the API description 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.
## Development

2
__tests__/lint-config/invalid-config--lint-config-error/snapshot.js
View File

@@ -19,7 +19,7 @@ Error was generated by the configuration spec rule.
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
[WARNING] Unused rules found in .redocly.yaml: context.
Check the spelling and verify the added plugin prefix.

2
__tests__/lint-config/invalid-config--lint-config-off/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint-config test with option: { dirName: 'invalid-config--lint-conf
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
[WARNING] Unused rules found in .redocly.yaml: context.
Check the spelling and verify the added plugin prefix.

2
__tests__/lint-config/invalid-config--lint-config-warn/snapshot.js
View File

@@ -19,7 +19,7 @@ You have 1 warning.
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
[WARNING] Unused rules found in .redocly.yaml: context.
Check the spelling and verify the added plugin prefix.

2
__tests__/lint-config/invalid-config--no-option/snapshot.js
View File

@@ -19,7 +19,7 @@ You have 1 warning.
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
[WARNING] Unused rules found in .redocly.yaml: context.
Check the spelling and verify the added plugin prefix.

2
__tests__/lint-config/invalid-config-assertation-config-type/snapshot.js
View File

@@ -22,7 +22,7 @@ The 'assert/' syntax in assert/path-item-mutually-required is deprecated. Update
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint-config/invalid-config-assertation-name/snapshot.js
View File

@@ -20,7 +20,7 @@ Error was generated by the configuration spec rule.
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
[WARNING] Unused rules found in .redocly.yaml: asset/path-item-mutually-required.
Check the spelling and verify the added plugin prefix.

2
__tests__/lint-config/invalid-config-format-json/snapshot.js
View File

@@ -17,7 +17,7 @@ exports[`E2E lint-config test with option: {
validating ../__fixtures__/valid-openapi.yaml...
../__fixtures__/valid-openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/assertions-camel-case-twice/snapshot.js
View File

@@ -33,7 +33,7 @@ Warning was generated by the rule/named-parameters-camelCase rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 2 warnings.

2
__tests__/lint/assertions-non-empty-off/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint assertions-non-empty-off 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/assertions-non-empty-warn/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the rule/summary-non-empty rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/assertions-type-integer-in-schema-response/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint assertions-type-integer-in-schema-response 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/assertions/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint assertions 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/async2/snapshot.js
View File

@@ -50,7 +50,7 @@ validating /streetlights-operation-security.yml...
validating /websocket-gemini.yml...
/websocket-gemini.yml: validated in <test>ms
Woohoo! Your OpenAPI definitions are valid. 🎉
Woohoo! Your API descriptions are valid. 🎉
`;

2
__tests__/lint/deprecated-apiDefinitions/snapshot.js
View File

@@ -49,7 +49,7 @@ Warning was generated by the info-contact rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/info-contact--lint-in-apis/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint info-contact--lint-in-apis 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/info-contact-not-present-warning/snapshot.js
View File

@@ -18,7 +18,7 @@ Warning was generated by the info-contact rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/info-contact/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint info-contact 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/info-license-rule-not-present-warning/snapshot.js
View File

@@ -18,7 +18,7 @@ Warning was generated by the info-license rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/info-license-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint info-license-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/info-license-url-missing-warning/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the info-license-url rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/info-license-url-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint info-license-url-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/merge-lint-configs/snapshot.js
View File

@@ -18,7 +18,7 @@ Warning was generated by the info-contact rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/no-empty-servers-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-empty-servers-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-empty-servers-warning/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the no-empty-servers rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/no-enum-type-mismatch/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-enum-type-mismatch 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-invalid-media-type-examples-recursion-oneOf/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-invalid-media-type-examples-recursion-oneOf 1`] = `
validating /openapi.json...
/openapi.json: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-invalid-media-type-examples-recursion/snapshot.js
View File

@@ -42,7 +42,7 @@ Warning was generated by the no-invalid-media-type-examples rule.
/openapi.json: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 2 warnings.

2
__tests__/lint/no-invalid-schema-examples-oas3.1/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-invalid-schema-examples-oas3.1 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-invalid-schema-examples/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-invalid-schema-examples 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-path-trailing-slash-off/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-path-trailing-slash-off 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-path-trailing-slash-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-path-trailing-slash-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-server-example-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-server-example-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-server-trailing-slash-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-server-trailing-slash-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-server-variables-empty-enum/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-server-variables-empty-enum 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-unresolved-refs-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-unresolved-refs-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-unused-components-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint no-unused-components-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/no-unused-components-warning/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the no-unused-components rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/oas2/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint oas2 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/oas3-no-errors/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint oas3-no-errors 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/oas3.1/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the no-unused-components rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/operation-2xx-response-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-2xx-response-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-2xx-response-warning/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the operation-2xx-response rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/operation-4xx-response-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-4xx-response-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-4xx-response-warning/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the operation-4xx-response rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/operation-description-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-description-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-description-warning/snapshot.js
View File

@@ -19,7 +19,7 @@ Warning was generated by the operation-description rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/operation-operationId-in-callback/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-operationId-in-callback 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-operationId-unique-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-operationId-unique-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-parameters-unique-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-parameters-unique-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-security-defined-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-security-defined-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/operation-security-defined-warning/snapshot.js
View File

@@ -18,7 +18,7 @@ Warning was generated by the security-defined rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/operation-tag-defined-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint operation-tag-defined-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/parameter-description-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint parameter-description-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/parameter-description-warning/snapshot.js
View File

@@ -71,7 +71,7 @@ Warning was generated by the parameter-description rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 4 warnings.

2
__tests__/lint/path-declaration-must-exist-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint path-declaration-must-exist-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/path-not-include-query-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint path-not-include-query-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/path-parameters-defined-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint path-parameters-defined-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/path-segment-plural/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint path-segment-plural 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/tags-alphabetical-rule/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint tags-alphabetical-rule 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/tags-alphabetical-warning/snapshot.js
View File

@@ -25,7 +25,7 @@ Warning was generated by the tags-alphabetical rule.
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

2
__tests__/lint/test-unused-component/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint test-unused-component 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/lint/with-ignore-file/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`E2E lint with-ignore-file 1`] = `
validating /openapi.yaml...
/openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
2 problems are explicitly ignored.

4
__tests__/miscellaneous/resolve-refs-in-preprocessors/snapshot.js
View File

@@ -66,7 +66,7 @@ Info object should contain \`license\` field.
Warning was generated by the info-license rule.
Woohoo! Your OpenAPI definitions are valid. 🎉
Woohoo! Your API descriptions are valid. 🎉
You have 1 warning.
bundling openapi.yaml...
@@ -93,7 +93,7 @@ Warning was generated by the info-license rule.
openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
You have 1 warning.

4
__tests__/split/missing-outDir/snapshot.js
View File

@@ -4,10 +4,10 @@ exports[`E2E split without option: outDir 1`] = `
index.ts split [api]
Split an API definition into a multi-file structure.
Split an API description into a multi-file structure.
Positionals:
api API definition file that you want to split [string] [required]
api API description file that you want to split [string] [required]
Options:
--version Show version number. [boolean]

2
__tests__/webpack-bundle/bundle/snapshot.js
View File

@@ -2,7 +2,7 @@
exports[`webpack-bundle test bundle check 1`] = `
Woohoo! Your OpenAPI definitions are valid. 🎉
Woohoo! Your API descriptions are valid. 🎉
bundling ./openapi.yaml...
📦 Created a bundle for ./openapi.yaml at /tmp/null.yaml <test>ms.

2
__tests__/webpack-bundle/lint-workflows/snapshot.js
View File

@@ -13,7 +13,7 @@ exports[`webpack-bundle test lint-workflows 1`] = `
validating ./openapi.yaml...
./openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

2
__tests__/webpack-bundle/lint/snapshot.js
View File

@@ -5,7 +5,7 @@ exports[`webpack-bundle test lint check 1`] = `
validating ./openapi.yaml...
./openapi.yaml: validated in <test>ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
`;

40
docs/changelog.md
View File

@@ -13,7 +13,7 @@ toc:
### Minor Changes
- Added `ignoreCase` option for `tags-alphabetical` rule.
- Added `join` support for OAS 3.1 definitions.
- Added `join` support for OAS 3.1 descriptions.
- Added support for Redoc v2.1.2, and aligned the dependencies for both projects.
### Patch Changes
@@ -150,7 +150,7 @@ No code changes.
- Fixed a bug with OAS (`x-`) specification extensions that contain an array.
- Display an error if the API path refers to a folder.
- Fixed the `push` command not recognizing API definitions with spaces.
- Fixed the `push` command not recognizing API descriptions with spaces.
- Defined default `allowedValues` in the `all` ruleset for mime-type rules.
### Changes
@@ -164,7 +164,7 @@ No code changes.
### Features
- Added the [required-min-length-string-type-property](./rules/required-string-property-missing-min-length.md) rule that requires required properties in the API definition with type `string` to have a `minLength`.
- Added the [required-min-length-string-type-property](./rules/required-string-property-missing-min-length.md) rule that requires required properties in the API description with type `string` to have a `minLength`.
### Fixes
@@ -231,7 +231,7 @@ theme:
### Fixes
- Fixed an issue where the `spec` rule showed an error for `x-logo` properties in the 3.1 OpenAPI definition.
- Fixed an issue where the `spec` rule showed an error for `x-logo` properties in the 3.1 OpenAPI description.
## 1.0.0-beta.118 (2022-12-29)
@@ -239,7 +239,7 @@ theme:
- Enabled removing unused components in the config to use within the bundle command.
- Implemented special SpecExtension type `VendorExtension`.
- Added an error handler for the case when the definition or a plugin does not exist.
- Added an error handler for the case when the API description file or a plugin does not exist.
- Added `media-type-examples-override` decorator.
### Fixes
@@ -467,7 +467,7 @@ Broken release.
### Features
- Added the `--public` option to the `push` command. With this option, you can upload OpenAPI definitions and make them publicly accessible.
- Added the `--public` option to the `push` command. With this option, you can upload OpenAPI descriptions and make them publicly accessible.
- Changed assertions syntax to this pattern: `assert/{assert name}`
### Fixes
@@ -595,7 +595,7 @@ rules:
### Fixes
- Fixed an issue with the `lint` command highlighting the entire file when `servers` are missing in OAS3. Now it highlights only the `openapi` field, indicating an incorrect OpenAPI definition.
- Fixed an issue with the `lint` command highlighting the entire file when `servers` are missing in OAS3. Now it highlights only the `openapi` field, indicating an incorrect OpenAPI description.
- Fixed an issue with the `lint` command highlighting all parent values when one of the child fields has an empty value instead of highlighting the field itself.
---
@@ -631,7 +631,7 @@ rules:
### Fixes
- Fixed an issue with the `lint` command crashing when the `servers.url` field is empty in the OpenAPI definition.
- Fixed an issue with the `lint` command crashing when the `servers.url` field is empty in the OpenAPI description.
- Fixed an issue with the `lint` command crashing when an `enum` value is invalid.
---
@@ -785,7 +785,7 @@ rules:
- Fixed an issue with hot reloading when running a preview of reference docs with `openapi preview-docs`.
- Fixed an issue with page refresh when pagination is set to `item` or `section`.
- Fixed an issue with inlining external schema when components' names match.
- Fixed an issue with fetching hosted schema on Windows when bundling OAS definitions.
- Fixed an issue with fetching hosted schema on Windows when bundling OpenAPI descriptions.
- Fixed an issue for `no-server-trailing-slash` when server url is a root.
---
@@ -822,7 +822,7 @@ rules:
### Features
- Added three built-in decorators - `info-description-override`, `tag-description-override`, `operation-description-override` - that let you modify your API definitions during the bundling process. Use these decorators in the `lint` section of your `.redocly.yaml` file to point OpenAPI CLI to Markdown files with custom content. That custom content replaces any existing content in the `info.description` field, and in `tags.description` and `operation.description` fields for specified tag names and operation IDs.
- Added three built-in decorators - `info-description-override`, `tag-description-override`, `operation-description-override` - that let you modify your API descriptions during the bundling process. Use these decorators in the `lint` section of your `.redocly.yaml` file to point OpenAPI CLI to Markdown files with custom content. That custom content replaces any existing content in the `info.description` field, and in `tags.description` and `operation.description` fields for specified tag names and operation IDs.
The following examples show how to add the decorators to the `.redocly.yaml` file:
@@ -863,7 +863,7 @@ lint:
- Fixed an issue with the `--format` option not working with the `bundle` command.
- Fixed a validation issue with the non-string `openapi` value in API definitions. The `lint` command now warns if the value is not string instead of crashing.
- Fixed a validation issue with the non-string `openapi` value in API descriptions. The `lint` command now warns if the value is not string instead of crashing.
---
@@ -1029,7 +1029,7 @@ lint:
### Features
- Implemented support for [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0). You can now lint, validate, and bundle your OAS 3.1 definitions with OpenAPI CLI.
- Implemented support for [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0). You can now lint, validate, and bundle your OAS 3.1 descriptions with OpenAPI CLI.
---
@@ -1053,7 +1053,7 @@ lint:
### Fixes
- The root API definition document is now parsed in all cases, even if it doesn't report the correct MIME type or doesn't use any of the supported file extensions.
- The root API description document is now parsed in all cases, even if it doesn't report the correct MIME type or doesn't use any of the supported file extensions.
---
@@ -1085,7 +1085,7 @@ lint:
### Fixes
- Resolved a hot-reloading issue with the `preview-docs` command. It now automatically reloads the docs in the browser when you make live changes to an OpenAPI definition.
- Resolved a hot-reloading issue with the `preview-docs` command. It now automatically reloads the docs in the browser when you make live changes to an OpenAPI description.
---
@@ -1183,7 +1183,7 @@ lint:
### Features
- A new command called `push` is now supported by OpenAPI CLI. With this command, you can upload your API definitions and associated files, and set up your own CI pipeline for updating API definitions without granting Redocly Workflows access to your repositories.
- A new command called `push` is now supported by OpenAPI CLI. With this command, you can upload your API descriptions and associated files, and set up your own CI pipeline for updating API descriptions without granting Redocly Workflows access to your repositories.
### Fixes
@@ -1197,7 +1197,7 @@ lint:
- Resolved an issue with `assert-node-version` using the wrong path.
- OpenAPI CLI bundles the API definition before gathering stats.
- OpenAPI CLI bundles the API description before gathering stats.
---
@@ -1215,7 +1215,7 @@ lint:
### Features
- A new command called `join` is now available in OpenAPI CLI. Use it to combine two or more API definition files into one. The resulting file optionally helps distinguish the origin of OpenAPI objects and properties by appending custom prefixes to them. Note that this command is considered experimental; meaning, it's still a work in progress.
- A new command called `join` is now available in OpenAPI CLI. Use it to combine two or more API description files into one. The resulting file optionally helps distinguish the origin of OpenAPI objects and properties by appending custom prefixes to them. Note that this command is considered experimental; meaning, it's still a work in progress.
---
@@ -1231,7 +1231,7 @@ lint:
### Features
- OpenAPI CLI now supports the `split` command, which you can use to create a multi-file structure out of an API definition file by extracting referenced parts into standalone, separate files. The command doesn't support OAS 2.
- OpenAPI CLI now supports the `split` command, which you can use to create a multi-file structure out of an API description file by extracting referenced parts into standalone, separate files. The command doesn't support OAS 2.
### Fixes
@@ -1243,7 +1243,7 @@ lint:
### Features
- A new command called `stats` has been implemented. It provides statistics about the structure of one or more API definition files, and lets you choose the format in which the statistics are presented.
- A new command called `stats` has been implemented. It provides statistics about the structure of one or more API description files, and lets you choose the format in which the statistics are presented.
### Fixes
@@ -1375,7 +1375,7 @@ lint:
- Resolved an issue with detecting output file extension without an entrypoint.
- Resolved an issue with the `preview-docs` command failing to automatically select the first definition from the `apiDefinitions` section of the configuration file when used without arguments.
- Resolved an issue with the `preview-docs` command failing to automatically select the first description from the `apiDefinitions` section of the configuration file when used without arguments.
- Fixed an issue with relative paths for entrypoints from external configuration files.

6
docs/commands/build-docs.md
View File

@@ -18,11 +18,11 @@ redocly build-docs <api> -t custom.hbs --templateOptions.metaDescription "Page m
| Option | Type | Description |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | Path to the API definition filename or alias that you want to generate the build for. Refer to the [API examples](#api-examples) for more information. |
| api | string | Path to the API description filename or alias that you want to generate the build for. Refer to the [API examples](#api-examples) for more information. |
| --output, -o | string | Sets the path and name of the output file. The default value is `redoc-static.html`. |
| --title | string | Sets the page title. |
| --disableGoogleFont | boolean | Disables Google fonts. The default value is `false`. |
| --template, -t | string | Uses custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI definition. |
| --template, -t | string | Uses custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI description. |
| --templateOptions | string | Adds template options you want to pass to your custom Handlebars template. To add options, use dot notation. |
| --theme.openapi | string | Customizes your output with [Redoc functionality options](https://redocly.com/docs/api-reference-docs/configuration/functionality/) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming/). |
| --config | string | Specifies path to the [configuration file](#custom-configuration-file). |
@@ -55,7 +55,7 @@ redocly build-docs games@v1
```yaml Configuration file
apis:
games@v1:
root: ./openapi/definition.json
root: ./openapi/api-description.json
```
The `build-docs` command uses any additional configurations provided in the file.

16
docs/commands/bundle.md
View File

@@ -2,9 +2,9 @@
## Introduction
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.
API descriptions 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 description by referencing them with `$ref`. However, most OpenAPI tools don't support that multi-file approach, and require a single-file API description.
Redocly CLI can help you combine separate API definition files (such as if you used the `split` command) 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 description files (such as if you used the `split` command) into one. The `bundle` command pulls the relevant parts of an API description into a single file output in JSON or YAML format.
The `bundle` command first executes preprocessors, then rules, then decorators.
@@ -22,7 +22,7 @@ redocly bundle --version
| Option | Type | Description |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apis | [string] | List of API root definition filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file. |
| apis | [string] | List of API description root filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file. |
| --config | string | Specify path to the [config file](#custom-configuration-file). |
| --dereferenced, -d | boolean | Generate fully dereferenced bundle. |
| --ext | string | Specify bundled file extension. Possible values are `json`, `yaml`, or `yml`. Default value is `yaml`. |
@@ -31,7 +31,7 @@ redocly bundle --version
| --format | string | Format for the output. Possible values are `codeframe`, `stylish`, `json`, or `checkstyle`. Default value is `codeframe`. |
| --help | boolean | Show help. |
| --keep-url-references, -k | boolean | Keep absolute url references. |
| --lint | boolean | Lint definition files. Default value is `false`. |
| --lint | boolean | Lint API description files. Default value is `false`. |
| --max-problems | integer | Truncate output to display the specified maximum number of problems. Default value is `100`. |
| --metafile | string | Path for the bundle metadata file. |
| --output, -o | string | Name or folder for the bundle file. If you don't specify the file extension, `.yaml` is used by default. If the specified folder doesn't exist, it's created automatically. **If the file specified as the bundler's output already exists, it's overwritten.** |
@@ -43,15 +43,15 @@ redocly bundle --version
## Examples
### Bundle a single API definition
### Bundle a single API description
This command creates a bundled file at the path `dist/openapi.json` starting from the root API definition file `openapi/openapi.yaml` and following the `$ref` to other files if appropriate. The bundled file is in JSON format.
This command creates a bundled file at the path `dist/openapi.json` starting from the root API description file `openapi/openapi.yaml` and following the `$ref` to other files if appropriate. The bundled file is in JSON format.
```bash
redocly bundle openapi/openapi.yaml --output dist/openapi.json
```
### Bundle multiple API definitions
### Bundle multiple API descriptions
This command creates one bundled file for each of the specified apis in the `dist/` folder. Bundled files are in JSON format.
@@ -66,7 +66,7 @@ dist/petstore.json
### Create a fully dereferenced bundle
A fully dereferenced bundle does not use `$ref` at all, all the references are resolved and placed into the definition file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the `$ref` syntax.
A fully dereferenced bundle does not use `$ref` at all, all the references are resolved and placed into the API description file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the `$ref` syntax.
```bash
redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml

14
docs/commands/index.md
View File

@@ -6,25 +6,25 @@ tocMaxDepth: 2
Documentation commands:
- [`preview-docs`](preview-docs.md) Preview API reference docs for the specified definition.
- [`build-docs`](build-docs.md) Build definition into an HTML file.
- [`preview-docs`](preview-docs.md) Preview API reference docs for the specified API description.
- [`build-docs`](build-docs.md) Build API description into an HTML file.
API management commands:
- [`stats`](stats.md) Gathering statistics for a document.
- [`bundle`](bundle.md) Bundle definition.
- [`split`](split.md) Split definition into a multi-file structure.
- [`join`](join.md) Join definitions [experimental feature].
- [`bundle`](bundle.md) Bundle API description.
- [`split`](split.md) Split API description into a multi-file structure.
- [`join`](join.md) Join API descriptions [experimental feature].
Linting commands:
- [`lint`](lint.md) Lint definition.
- [`lint`](lint.md) Lint API description.
Redocly platform commands:
- [`login`](login.md) Login to the Redocly API registry with an access token.
- [`logout`](logout.md) Clear your stored credentials for the Redocly API registry.
- [`push`](push.md) Push an API definition to the Redocly API registry.
- [`push`](push.md) Push an API description to the Redocly API registry.
Supporting commands:

16
docs/commands/join.md
View File

@@ -10,19 +10,19 @@ tocMaxDepth: 3
The `join` command is considered an experimental feature. This means it's still a work in progress and may go through major changes.
The `join` command supports OpenAPI 3.x definitions only.
The `join` command supports OpenAPI 3.x descriptions 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.
Maintainers of multiple API descriptions can benefit from storing each endpoint as a standalone API description file. However, this approach is not supported by the majority of OpenAPI tools, as they require a single API description file.
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.
With Redocly CLI, you can solve this problem by using the `join` command that can combine two or more API description 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.
The `join` command accepts both YAML and JSON files, which you can mix in the resulting `openapi.yaml` file. Setting a custom name for this file can be achieved by providing it through the `--output` argument. Any existing file is overwritten.
Apart from providing individual API definition files as the input, you can also specify the path to a folder that contains multiple API definition files and match them with a wildcard (for example, `myproject/openapi/*.yaml`). The `join` command collects all matching files and combines them into one file.
Apart from providing individual API description files as the input, you can also specify the path to a folder that contains multiple API description files and match them with a wildcard (for example, `myproject/openapi/*.yaml`). The `join` command collects all matching files and combines them into one file.
### Usage
@@ -43,9 +43,9 @@ redocly join --version
| Option | Type | Description |
| ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apis | [string] | **REQUIRED.** 1. Array of paths to API definition files that you want to join. At least two input files are required.<br />2. A wildcard pattern to match API definition files within a specific folder. |
| apis | [string] | **REQUIRED.** 1. Array of paths to API description files that you want to join. At least two input files are required.<br />2. A wildcard pattern to match API description files within a specific folder. |
| --help | boolean | Show help. |
| --lint | boolean | Lint definition files. |
| --lint | boolean | Lint API description files. |
| --decorate | boolean | Run decorators. |
| --preprocess | boolean | Run preprocessors. |
| --prefix-tags-with-filename | string | Prefix tags with property value from file name. See the [prefix-tags-with-filename section](#prefix-tags-with-filename) below. |
@@ -72,7 +72,7 @@ openapi.yaml: join processed in 56ms
The command creates the output `openapi.yaml` file in the working directory.
The order of input files affects how their content is processed. The first provided file is always treated as the "main" file, and its content has precedence over other input files when combining them. Specifically, the following properties of the API definition are always taken only from the first input file:
The order of input files affects how their content is processed. The first provided file is always treated as the "main" file, and its content has precedence over other input files when combining them. Specifically, the following properties of the API description are always taken only from the first input file:
```yaml
info:
@@ -185,7 +185,7 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
### without-x-tag-groups
If you have the same tags in multiple API definitions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.
If you have the same tags in multiple API descriptions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.
#### Usage

20
docs/commands/lint.md
View File

@@ -2,7 +2,7 @@
## Introduction
Redocly 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 descriptions. This helps you avoid bugs and make API descriptions more consistent.
The `lint` command reports on problems and executes preprocessors and rules. Unlike the `bundle` command, `lint` doesn't execute decorators.
@@ -26,7 +26,7 @@ redocly lint --version
| Option | Type | Description |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| apis | [string] | Array of API definition filenames that need to be linted. See [the Apis section](#apis) for more options. |
| apis | [string] | Array of API description filenames that need to be linted. See [the Apis section](#apis) for more options. |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| --extends | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). |
| --format | string | Format for the output.<br />**Possible values:** `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `summary`. Default value is `codeframe`. |
@@ -50,7 +50,7 @@ The `lint` command behaves differently depending on how you pass apis to it and
redocly lint openapi/openapi.yaml
```
In this case, `lint` validates the definition(s) passed to the command. If you have no configuration file defined, the [recommended ruleset](../rules/recommended.md) is used. If you have `extends` or `rules` defined in `redocly.yaml`, those are used when linting.
In this case, `lint` validates the API description(s) passed to the command. If you have no configuration file defined, the [recommended ruleset](../rules/recommended.md) is used. If you have `extends` or `rules` defined in `redocly.yaml`, those are used when linting.
The `apis` argument can also use any glob format supported by your file system. For example, `redocly lint ./root-documents/*.yaml`.
@@ -65,10 +65,10 @@ redocly lint core@v1
```yaml Configuration file
apis:
core@v1:
root: ./openapi/definition.json
root: ./openapi/api-description.json
```
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `definition.json` file. The presence of the Redocly configuration file is mandatory.
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `api-description.json` file. The presence of the Redocly configuration file is mandatory.
#### All configured APIs
@@ -81,14 +81,14 @@ redocly lint
```yaml Configuration file
apis:
core@v1:
root: ./openapi/definition.json
root: ./openapi/api-description.json
production:
root: ./openapi/production.yaml
sandbox:
root: ./openapi/sandbox.yaml
```
In this case, if no API definitions are specified, `lint` validates all apis listed under `apis` in your Redocly configuration file. The presence of the configuration file is mandatory.
In this case, if no API descriptions are specified, `lint` validates all apis listed under `apis` in your Redocly configuration file. The presence of the configuration file is mandatory.
:::warning Important
@@ -191,7 +191,7 @@ redocly lint --format=json
"location": [
{
"source": {
"ref": "mydefinition.yaml"
"ref": "myapi.yaml"
},
"pointer": "#/paths/~1pathItem/post/operationIdentifier",
"reportOnKey": true
@@ -205,7 +205,7 @@ redocly lint --format=json
"location": [
{
"source": {
"ref": "mydefinition.yaml"
"ref": "myapi.yaml"
},
"pointer": "#/paths/~1pathItem/post/operationId",
"reportOnKey": true
@@ -271,7 +271,7 @@ Generated ignore file with 3 problems.
This command overwrites an existing ignore file.
:::
To generate an ignore file for multiple definitions, pass them as arguments:
To generate an ignore file for multiple API descriptions, pass them as arguments:
```bash
redocly lint v1.yaml v2.yaml --generate-ignore-file

2
docs/commands/login.md
View File

@@ -6,7 +6,7 @@ Use the `login` command to authenticate to the API registry.
When you log in, the `preview-docs` command starts a preview server using Redocly API reference docs with all of the premium features. Users who are not logged in see a Redoc community edition version of their documentation.
Also, you can access your members-only (private) API definitions in the Redocly registry, and use the [`push`](./push.md) command.
Also, you can access your members-only (private) API descriptions in the Redocly registry, and use the [`push`](./push.md) command.
If you're having issues with the `login` command, use the `--verbose` option to display a detailed error trace (if any).

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

@@ -2,7 +2,7 @@
## Introduction
With this command, you can generate documentation previews for API definitions on your local machine.
With this command, you can generate documentation previews for API descriptions on your local machine.
If you have a license key or API key configured, the output is a preview of the premium [Redocly API reference docs](https://redocly.com/reference/). Otherwise, it is a preview of [Redoc community edition](https://redocly.com/redoc/).
@@ -23,7 +23,7 @@ redocly preview-docs <api> --version
| Option | Type | Description |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | Path to the API definition filename or alias that you want to generate the preview for. Refer to [the api section](#api) for more options. |
| api | string | Path to the API description filename or alias that you want to generate the preview for. Refer to [the api section](#api) for more options. |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| --force, -f | boolean | Generate preview output even when errors occur. |
| --help | boolean | Show help. |
@@ -46,7 +46,7 @@ The command behaves differently depending on how you pass the api to it, and whe
redocly preview-docs openapi/openapi.yaml
```
In this case, `preview-docs` previews the definition that was passed to the command. The configuration file is ignored.
In this case, `preview-docs` previews the API description that was passed to the command. The configuration file is ignored.
#### Pass api alias
@@ -59,10 +59,10 @@ redocly preview-docs core@v1
```yaml Configuration file
apis:
core@v1:
root: ./openapi/definition.json
root: ./openapi/api-description.json
```
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `preview-docs` generates a preview of the `definition.json` file. For this approach, the Redocly configuration file is mandatory.
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `preview-docs` generates a preview of the `api-description.json` file. For this approach, the Redocly configuration file is mandatory.
### Custom configuration file

42
docs/commands/push.md
View File

@@ -2,16 +2,16 @@
## Introduction
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.
Redocly Workflows integrates with [popular version control services](../../workflows/sources/index.md) and uses them as the source of your API descriptions 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 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
The Redocly CLI `push` command helps you automate API description 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 descriptions are generated automatically from code annotations in a CI/CD pipeline
This allows you to:
- Benefit from using Redocly Workflows to preview documentation and portal builds.
- Manage versions in the API registry.
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:
Apart from uploading your API description file, the `push` command can automatically upload other files if they are detected or referenced in the API description:
- the [Redocly configuration file](../configuration/index.mdx) and any configuration files referenced in the `extends` list.
- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows uses the `@redocly/cli` version specified in `package.json`.
@@ -25,11 +25,11 @@ Make sure that each plugin has all the required files in its folder; otherwise,
:::
By default, the `push` command only updates an existing API definition version. If an API with the provided name and version doesn't exist in your organization, it isn't created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section.
By default, the `push` command only updates an existing API description version. If an API with the provided name and version doesn't exist in your organization, it isn't created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section.
:::warning
Only API definitions with a CI source can be updated with the `push` command. Attempting to update API definitions created from other sources fails with an error.
Only API descriptions with a CI source can be updated with the `push` command. Attempting to update API descriptions created from other sources fails with an error.
:::
@@ -71,21 +71,21 @@ To authenticate to the API registry, you can use several approaches:
```bash
redocly push [api] [--destination] [--organization]
redocly push
redocly push [-u] [--job-id id] [--batch-size number] <path/to/definition.yaml> [--destination] [--organization] [--branch]
redocly push [-u] [--job-id id] [--batch-size number] <path/to/api-description.yaml> [--destination] [--organization] [--branch]
```
## Options
| Option | Type | Description |
| ---------------- | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | The API definition that you want to push to the Redocly API registry. Provide it as a path to the root API definition file (or as an alias). See [Set options explicitly](#set-options-explicitly) for more information. |
| --destination | string | The location in the API registry where you want to push or upsert your API definition. Provide it in the following format: `api-name@api-version`. |
| --organization | string | ID of organization that the definition is being pushed to. Overrides the one defined in the config file. |
| --branch, -b | string | The branch where your API definition is pushed or upserted. Default value is `main`. |
| api | string | The API description that you want to push to the Redocly API registry. Provide it as a path to the root API description file (or as an alias). See [Set options explicitly](#set-options-explicitly) for more information. |
| --destination | string | The location in the API registry where you want to push or upsert your API description. Provide it in the following format: `api-name@api-version`. |
| --organization | string | ID of organization that the API description is being pushed to. Overrides the one defined in the config file. |
| --branch, -b | string | The branch where your API description is pushed or upserted. Default value is `main`. |
| --job-id | string | The ID of the CI job that the current push is associated with. See [the Job ID section](#job-id) for more information. |
| --batch-size | number | Number of CI pushes expected within one batch. See [the Batch Size section](#batch-size) for more information. |
| --help | boolean | Help output for the command. |
| --public | boolean | Make API definitions publicly accessible from the API Registry. Read more about [using the public option](#public). |
| --public | boolean | Make API descriptions publicly accessible from the API Registry. Read more about [using the public option](#public). |
| --region,-r | string | Which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. Alternatively, set an environment variable `REDOCLY_DOMAIN` with the value of the appropriate Redocly API. |
| --skip-decorator | [string] | Ignore one or more decorators. See the [Skip decorator section](#skip-decorator) for usage examples. |
| --upsert, -u | boolean | Create a new version of an API when pushing to the API registry if the version doesn't exist. See [the Upsert an API with push section](#upsert-an-api-with-push) for more information. |
@@ -103,7 +103,7 @@ You can choose any of the following approaches:
### Destination
To properly push your API definition to the Redocly API registry, you need the following information:
To properly push your API description to the Redocly API registry, you need the following information:
- [Organization ID](#organization-id)
- [API name and version](#api-name-and-version)
@@ -160,15 +160,15 @@ The version of your API should contain only supported characters (`a-z`, `A-Z`,
### Set options explicitly
Provide the `api` as a path to the root API definition file, and specify the organization ID, API name and version.
Provide the `api` as a path to the root API description file, and specify the organization ID, API name and version.
```bash
redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org
```
In this case, `push` uploads only the definition that was passed to the command. The configuration file is ignored.
In this case, `push` uploads only the API description that was passed to the command. The configuration file is ignored.
To push the definition to a particular branch, specify the branch name.
To push the API description to a particular branch, specify the branch name.
```bash
redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org -b develop
@@ -176,7 +176,7 @@ redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=
### Set options in the configuration file
Depending on the contents of your Redocly configuration file, you can use simplified `push` syntax instead of providing the full path to the API definition file.
Depending on the contents of your Redocly configuration file, you can use simplified `push` syntax instead of providing the full path to the API description file.
**Example configuration file**
@@ -184,7 +184,7 @@ Depending on the contents of your Redocly configuration file, you can use simpli
organization: organization-id
apis:
api-name@api-version:
root: path/to/root/definition.yaml
root: path/to/root/api-description.yaml
another-api:
root: openapi/openapi.yaml
```
@@ -223,7 +223,7 @@ redocly push -u --destination=test-api@v1
redocly push -u
```
To upsert the definition to a particular branch, specify the branch name with `--branch` or `-b`.
To upsert the API description to a particular branch, specify the branch name with `--branch` or `-b`.
```bash Set options explicitly
redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org -b develop
@@ -264,7 +264,7 @@ redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=
### Public
The `--public` option allows you to upload your API definition and make it publicly accessible from the API Registry. By default, definitions uploaded with the `push` command are not available to the public.
The `--public` option allows you to upload your API description and make it publicly accessible from the API Registry. By default, API descriptions uploaded with the `push` command are not available to the public.
For more information on how to configure access to your APIs, check the [registry access](../../../api-registry/settings/manage-access/#set-up-access-to-api-registry) section.
```bash
@@ -298,5 +298,5 @@ files:
The Redocly Workflows interface can help you get started with the `push` command.
1. In **API registry**, select **Add API**.
1. In the **Definition name** step, provide a name for your new API definition.
1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API definition file. Or use the `redocly push -u` command directly from the command-line interface.
1. In the **Definition name** step, provide a name for your new API description.
1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API description file. Or use the `redocly push -u` command directly from the command-line interface.

8
docs/commands/split.md
View File

@@ -2,12 +2,12 @@
## Introduction
The `split` command takes an API definition file and creates a [multi-file structure](../../resources/multi-file-definitions.md) out of it by extracting referenced parts into standalone, separate files. The advantage of this approach is making smaller files that are easier to manage and a structure that makes reviewing simpler.
The `split` command takes an API description file and creates a [multi-file structure](../../resources/multi-file-definitions.md) out of it by extracting referenced parts into standalone, separate files. The advantage of this approach is making smaller files that are easier to manage and a structure that makes reviewing simpler.
Use `bundle` and supply the main file as the entrypoint to get your OpenAPI description in one file. Many OpenAPI tools prefer a single file, but `split` and `bundle` allow you to manage your files easily for development, and then prepare a single file for other tools to consume.
:::warning OpenAPI 3.x only
The `split` command doesn't support OpenAPI 2.0 definitions.
The `split` command doesn't support OpenAPI 2.0 descriptions.
:::
## Usage
@@ -22,7 +22,7 @@ redocly split --version
| Option | Type | Description |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | **REQUIRED.** Path to the API definition file that you want to split into a multi-file structure. |
| api | string | **REQUIRED.** Path to the API description file that you want to split into a multi-file structure. |
| --outDir | string | **REQUIRED.** Path to the directory where you want to save split files. If the specified directory doesn't exist, it is created automatically. |
| --help | boolean | Show help. |
| --separator | string | File path separator used while splitting. The default value is `_`. This controls the file names generated in the `paths` folder (e.g. `/users/create` path becomes `user_create.yaml`). |
@@ -42,4 +42,4 @@ Document: pet.yaml is successfully split
pet.yaml: split processed in 33ms
```
In the `openapi` directory, the `split` command "unbundles" the specified API definition. Code samples, components, and paths are split from the root definition into separate files and folders. The structure of the unbundled directory corresponds to the structure created by our [openapi-starter](https://github.com/Redocly/openapi-starter) tool.
In the `openapi` directory, the `split` command "unbundles" the specified API description. Code samples, components, and paths are split from the root API description into separate files and folders. The structure of the unbundled directory corresponds to the structure created by our [openapi-starter](https://github.com/Redocly/openapi-starter) tool.

10
docs/commands/stats.md
View File

@@ -2,7 +2,7 @@
## Introduction
The `stats` command provides statistics about the structure of one or more API definition files. Statistics are calculated using the counting logic from the `StatsVisitor` module. The `stats` command can generate statistics for the following metrics:
The `stats` command provides statistics about the structure of one or more API description files. Statistics are calculated using the counting logic from the `StatsVisitor` module. The `stats` command can generate statistics for the following metrics:
- `References`
- `External Documents`
@@ -25,7 +25,7 @@ redocly stats --version
| Option | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------------------- |
| api | string | **REQUIRED.** Path to the API definition file that you want to split into a multi-file structure. |
| api | string | **REQUIRED.** Path to the API description 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. |
@@ -43,7 +43,7 @@ The `stats` command behaves differently depending on how you pass the api to it
redocly stats openapi/openapi.yaml
```
In this case, `stats` shows statistics for the definition that was passed to the command. The configuration file is ignored.
In this case, `stats` shows statistics for the API description that was passed to the command. The configuration file is ignored.
#### Pass api via configuration file
@@ -56,10 +56,10 @@ redocly stats core@v1
```yaml Configuration file
apis:
core@v1:
root: ./openapi/definition.json
root: ./openapi/api-description.json
```
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `stats` displays statistics for the `definition.json` file. The presence of the Redocly configuration file is mandatory.
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `stats` displays statistics for the `api-description.json` file. The presence of the Redocly configuration file is mandatory.
### Custom configuration file

10
docs/configuration/api.yaml
View File

@@ -1,7 +1,7 @@
type: object
title: APIs object
description: >-
Lets you configure one or more API definition files.
Lets you configure one or more API description files.
This gives you the flexibility to reference specific files in commands, and configure each file at a granular level.
additionalProperties:
x-additionalPropertiesName: '{name}@{version}'
@@ -11,12 +11,12 @@ additionalProperties:
required:
- root
description: >-
Specifies the name and version of an API associated with the root API definition with the pattern `{name}@{version}`.
Specifies the name and version of an API associated with the root API description with the pattern `{name}@{version}`.
If the version is omitted, Redocly apps interpret it as 'latest' by default.
properties:
root:
type: string
description: The path to the root API definition file of the specified API.
description: The path to the root API description file of the specified API.
labels:
type: array
description: >-
@@ -117,12 +117,12 @@ additionalProperties:
openapi:
type: object
description: >-
Defines theming and functionality for an API definition.
Defines theming and functionality for an API description.
Supports the same format and options as the [root `openapi` object](https://redocly.com/docs/api-reference-docs/configuration/functionality/).
API-level configuration always overrides the root configuration.
mockServer:
type: object
description: >-
Defines mock server behavior for an API definition.
Defines mock server behavior for an API description.
Supports the same format and options as the root `mockServer` object.
API-level configuration always overrides the root configuration.

2
docs/configuration/apis.mdx
View File

@@ -9,7 +9,7 @@ Every API in the object is identified by its name and version in the format `nam
The version is optional, and when not provided, Redocly apps interpret it as `latest` by default.
Every `name@version` combination listed in the object must be unique.
For every API listed in the object, you must provide the path to the OpenAPI definition using the `root` property.
For every API listed in the object, you must provide the path to the OpenAPI description using the `root` property.
If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root settings are used.
If `rules`, `decorators`, or `preprocessors` are defined for an API, its settings apply together with the root configuration.

10
docs/configuration/index.mdx
View File

@@ -61,14 +61,14 @@ Read on to learn more about the various configuration sections and what you can
## Using configuration with Redocly CLI
Some of the Redocly CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` object as shortcuts for referencing API definitions.
You can tell the `lint` command to validate specific API definitions by using their names from the `apis` object, like in the following example:
Some of the Redocly CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` object as shortcuts for referencing API descriptions.
You can tell the `lint` command to validate specific API descriptions by using their names from the `apis` object, like in the following example:
```shell
redocly lint core@v2
```
On the other hand, if you run the command without specifying any aliases, it applies to all API definitions listed in the `apis` object of the configuration file.
On the other hand, if you run the command without specifying any aliases, it applies to all API descriptions listed in the `apis` object of the configuration file.
```shell
redocly lint
@@ -144,7 +144,7 @@ This object is optional.
#### openapi object
The `openapi` object is a property of the `theme` object and configures features and theming for API documentation generated from OpenAPI definitions.
The `openapi` object is a property of the `theme` object and configures features and theming for API documentation generated from OpenAPI descriptions.
If you need to apply different theming and functionality to individual APIs, add the theme `openapi` property to the appropriate API in the `apis` and `theme` object, and use the same options as the global `openapi` object.
@@ -206,7 +206,7 @@ The rules, decorators, pre-processors and configuration contained in the plugins
### Resolve non-public or non-remote URLs
Redocly automatically resolves any API registry link or public URL in your API definitions.
Redocly automatically resolves any API registry link or public URL in your API descriptions.
If you want to resolve links that are neither API registry links nor publicly accessible, set the `resolve` object in your configuration file.
Redocly CLI supports one `http` header per URL.

4
docs/configuration/mockserver.yaml
View File

@@ -5,13 +5,13 @@ properties:
errorIfForcedExampleNotFound:
description: >-
You can force specific examples to appear in the response by adding the optional `x-redocly-response-body-example` header to your requests.
If you pass an example ID that can't be found in the API definition, the mock server returns any other example unless `errorIfForcedExampleNotFound` is `true`.
If you pass an example ID that can't be found in the API description, the mock server returns any other example unless `errorIfForcedExampleNotFound` is `true`.
Then the mock server returns an error instead.
type: boolean
default: false
strictExamples:
description: >-
By default, the mock server automatically enhances responses with heuristics, such as substituting response fields with request parameter values.
If set as `true`, examples are returned in the response unmodified, and exactly how they are described in the OpenAPI definition.
If set as `true`, examples are returned in the response unmodified, and exactly how they are described in the OpenAPI description.
type: boolean
default: false

4
docs/configuration/resolve.yaml
View File

@@ -1,7 +1,7 @@
type: object
title: Resolve object
description: >-
All API registry links and public URLs in your API definitions automatically resolve.
All API registry links and public URLs in your API descriptions automatically resolve.
If you want to resolve links that are neither API registry links nor publicly accessible, include this object to add an HTTP request header.
If the URL matches multiple patterns, the first match takes priority.
@@ -13,7 +13,7 @@ properties:
type: boolean
description: >-
You can stop `lint` from resolving `$refs` in examples by setting this configuration option to `true`.
This does not affect `$ref` resolution in other parts of the API definition.
This does not affect `$ref` resolution in other parts of the API description.
default: false
http:
type: object

20
docs/configuration/schema.yaml
View File

@@ -3,7 +3,7 @@ properties:
organization:
type: string
description: |-
Stores your Redocly Workflows organization ID that the `push` command uses to push API definition files to the API registry.
Stores your Redocly Workflows organization ID that the `push` command uses to push API description files to the API registry.
If an organization ID is not passed explicitly in command-line arguments, `push` looks for it in `redocly.yaml`.
To find the organization ID:
@@ -40,7 +40,7 @@ properties:
type: object
title: APIs object
description: >-
Lets you configure one or more API definition files.
Lets you configure one or more API description files.
This gives you the flexibility to reference specific files in commands, and configure each file at a granular level.
additionalProperties:
x-additionalPropertiesName: '{name}@{version}'
@@ -49,12 +49,12 @@ properties:
required:
- root
description: >-
Specifies the name and version of an API associated with the root API definition with the pattern `{name}@{version}`.
Specifies the name and version of an API associated with the root API description with the pattern `{name}@{version}`.
If the version is omitted, Redocly apps interpret it as 'latest' by default.
properties:
root:
type: string
description: The path to the root API definition file of the specified API.
description: The path to the root API description file of the specified API.
labels:
type: array
description: >-
@@ -155,13 +155,13 @@ properties:
openapi:
type: object
description: >-
Defines theming and functionality for an API definition.
Defines theming and functionality for an API description.
Supports the same format and options as the [root `openapi` object](https://redocly.com/docs/api-reference-docs/configuration/functionality/).
API-level configuration always overrides root configuration.
mockServer:
type: object
description: >-
Defines mock server behavior for an API definition.
Defines mock server behavior for an API description.
Supports the same format and options as the root `mockServer` object.
API-level configuration always overrides root configuration.
preprocessors:
@@ -259,14 +259,14 @@ properties:
errorIfForcedExampleNotFound:
description: >-
You can force specific examples to appear in the response by adding the optional `x-redocly-response-body-example` header to your requests.
If you pass an example ID that can't be found in the API definition, the mock server returns any other example unless `errorIfForcedExampleNotFound` is `true`.
If you pass an example ID that can't be found in the API description, the mock server returns any other example unless `errorIfForcedExampleNotFound` is `true`.
Then the mock server returns an error instead.
type: boolean
default: false
strictExamples:
description: >-
By default, the mock server automatically enhances responses with heuristics, such as substituting response fields with request parameter values.
If you set `strictExamples:true`, examples are returned in the response unmodified, and exactly how they are described in the OpenAPI definition.
If you set `strictExamples:true`, examples are returned in the response unmodified, and exactly how they are described in the OpenAPI description.
type: boolean
default: false
openapi:
@@ -287,7 +287,7 @@ properties:
resolve:
type: object
description: >-
All API registry links and public URLs in your API definitions automatically resolve.
All API registry links and public URLs in your API descriptions automatically resolve.
If you want to resolve links that are neither API registry links nor publicly accessible, include this object to add an HTTP request header.
Use environment variables where possible.
properties:
@@ -295,7 +295,7 @@ properties:
type: boolean
description: >-
You can stop `lint` from resolving `$refs` in examples by setting this configuration option to `true`.
This does not affect `$ref` resolution in other parts of the API definition.
This does not affect `$ref` resolution in other parts of the API description.
default: false
http:
type: object

4
docs/custom-plugins/custom-rules.md
View File

@@ -10,7 +10,7 @@ Exhaust the above options first, because they are simpler and more maintainable
## Build the custom rule
Each rule is a function that returns an object with methods that Redocly CLI calls to "visit" nodes while traversing the definition document. The object keys are the node types that are encountered in the document. In this simple example, the custom plugin holds a rule that fails if any `operationId` is set to "test".
Each rule is a function that returns an object with methods that Redocly CLI calls to "visit" nodes while traversing the API description document. The object keys are the node types that are encountered in the document. In this simple example, the custom plugin holds a rule that fails if any `operationId` is set to "test".
To keep the plugin code manageable, each rule can go in its own file. This example is in `plugins/rules/opid-not-test.js`:
@@ -78,7 +78,7 @@ The context object contains additional functionality that is helpful for rules t
The context object also offers some additional functionality to resolve references and to return information about a problem to the user. The methods available are as follows:
- `resolve(node)` - Synchronously dereferences `$ref` node to its value. Works only with `$refs` from the original document. If you need to resolve a reference from another source, you can use the optional second parameter: `resolve(node, from: string)`.
- `report(descriptor)` - Reports a problem in the definition and returns information to the user. See [Report rule context](#report-rule-context) for more information.
- `report(descriptor)` - Reports a problem in the API description and returns information to the user. See [Report rule context](#report-rule-context) for more information.
## Report rule context

6
docs/custom-plugins/extended-types.md
View File

@@ -1,7 +1,7 @@
# Type extensions in plugins
Redocly CLI in its core has a type tree which defines the structure of the API definition.
Redocly CLI then uses it to do a type-aware traversal of an OpenAPI definition.
Redocly CLI in its core has a type tree which defines the structure of the API description.
Redocly CLI then uses it to do a type-aware traversal of an OpenAPI description.
The type tree is built from top level `Types` which can link to child types. For example, here is a [visual reference to the OpenAPI types structure](../../openapi-visual-reference/openapi-node-types.md). You can also check [the code itself](https://github.com/Redocly/redocly-cli/tree/main/packages/core/src/types) for information about specific versions of OpenAPI and other supported document types.
@@ -70,5 +70,5 @@ rules:
spec: warn
```
Now lint your API definition with `redocly lint openapi.yaml` and try removing the `lifecycle` field from within the `x-metadata` section. It's a required field, so you see an error if it's missing.
Now lint your API description with `redocly lint openapi.yaml` and try removing the `lifecycle` field from within the `x-metadata` section. It's a required field, so you see an error if it's missing.

2
docs/custom-plugins/index.md
View File

@@ -75,6 +75,6 @@ module.exports = {
Everything that is exported from a plugin relates to one of the supported document formats, such as OpenAPI v3. Plugins work by exporting an object containing a key-value mapping from a document format and version (`oas2` or `oas3` are supported) to an extension object (rules, preprocessors, decorators).
Before processing the definition document, Redocly CLI detects the document format and applies a corresponding set of extensions.
Before processing the API description document, Redocly CLI detects the document format and applies a corresponding set of extensions.

2
docs/decorators/media-type-examples-override.md
View File

@@ -32,7 +32,7 @@ decorators:
## Examples
Given this definition with example:
Given this API description with example:
```yaml
openapi: 3.0.0

4
docs/file-management.md
View File

@@ -21,7 +21,7 @@ The original file is unchanged, but look in the directory named by the `--outDir
* A `paths/` directory, with a file for each of the URLs in the API. All verbs for that endpoint are in this file.
* A `components/` directory containing subdirectories for each of the top-level keys, such as `schema`, and files for the individual data structures described in each section.
By keeping your API in this format, managing changes can be easier since it's clear which file (or files) have changed, making it easier to review as things change. Many common operations can be performed on the API description in this format, such as linting. Some tools prefer a single bundled OpenAPI definition, and it's common to bundle during CI (continuous integration) before doing other automated operations.
By keeping your API in this format, managing changes can be easier since it's clear which file (or files) have changed, making it easier to review as things change. Many common operations can be performed on the API description in this format, such as linting. Some tools prefer a single bundled OpenAPI description, and it's common to bundle during CI (continuous integration) before doing other automated operations.
## Bundle OpenAPI to a single file
@@ -47,7 +47,7 @@ Pass `--lint` to the bundle command to have Redocly CLI check your API meets the
This feature is experimental, and supports OpenAPI 3.x only
:::
When you have multiple APIs but want to publish a single definition file, the [`join`](./commands/join.md) may meet your needs. This can be useful when you are providing a combined offering and want to create unified documentation, or use a single input to other tools.
When you have multiple APIs but want to publish a single API description file, the [`join`](./commands/join.md) may meet your needs. This can be useful when you are providing a combined offering and want to create unified documentation, or use a single input to other tools.
Use the command to combine files like this:

10
docs/guides/hide-apis.md
View File

@@ -13,8 +13,8 @@ Follow along using our sample API provided with this tutorial to hide APIs, and
## Overview
In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI definition.
Once the definition is complete, generate an internal and an external version of the API.
In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI description.
Once the API description is complete, generate an internal and an external version of the API.
```mermaid
graph TD
@@ -35,9 +35,9 @@ This tutorial is most effective when you follow along and complete the steps.
- 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).
## Step 1: Add `x-internal` to the API definition
## Step 1: Add `x-internal` to the API description
In this step, mark which operations and properties of the API definition are for internal use.
In this step, mark which operations and properties of the API description are for internal use.
Open the `sample.yaml` file in your IDE. Changes are needed in a few places.
@@ -76,7 +76,7 @@ apis:
Let's explain what's going on here.
The `apis` object contains a collection of our APIs.
The `internal@latest` matches the expected configuration `{name@version}` pattern for each API.
The `root` is the path to the root of the API definition.
The `root` is the path to the root of the API description.
We only have one root API file (`sample.yaml`), but we want to generate two APIs from that SSOT.
To do that, we add another API to the API section.

2
docs/guides/hide-specification-extensions.md
View File

@@ -6,7 +6,7 @@ in your API and want to hide their details as well. For this purpose, you need a
## Overview
In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI definition.
In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI description.
Then generate an internal and an external version of the API.
```mermaid

2
docs/guides/migrate-from-swagger-cli.md
View File

@@ -56,7 +56,7 @@ Learn more about [configuring Redocly CLI](../configuration/index.mdx) in the do
## Bundle OpenAPI/Swagger into a single file
While the OpenAPI (and earlier Swagger) standards were designed to use `$ref` reference syntax and re-use definitions across mulitple files, not all tools support this. If there's a tool in your API lifecycle that needs a single file, you can still use mulitple files for the day-to-day work, and then "bundle" the API description into a single file for use by another tool.
While the OpenAPI (and earlier Swagger) standards were designed to use `$ref` reference syntax and re-use elements of API descriptions across mulitple files, not all tools support this. If there's a tool in your API lifecycle that needs a single file, you can still use mulitple files for the day-to-day work, and then "bundle" the API description into a single file for use by another tool.
With `swagger-cli` the command would be something like this:

2
docs/guides/replace-servers-url.md
View File

@@ -6,7 +6,7 @@ redirectFrom:
---
# Replace servers URL in different environments
Redocly allows you to use [custom decorators](../custom-plugins/custom-decorators.md) to modify content in the API definition during the bundling process.
Redocly allows you to use [custom decorators](../custom-plugins/custom-decorators.md) to modify content in the API description during the bundling process.
This page describes how to replace the server URL with a decorator for a given environment.

14
docs/guides/response-contains-property.md
View File

@@ -47,11 +47,11 @@ Make sure that the @redocly/cli has version `1.0.0-beta.99` or later
This guide is most effective when you follow along and complete the steps.
:::
## Case 0 - Check that the current OpenAPI definition is valid
## Case 0 - Check that the current OpenAPI description is valid
After downloading the `openapi-starter` repository, ensure that you installed the project's dependencies via `npm install`.
Once completed, in the project folder, execute the `npx redocly lint` command. You should receive confirmation that the OpenAPI definition is valid:
Once completed, in the project folder, execute the `npx redocly lint` command. You should receive confirmation that the OpenAPI description is valid:
```bash
npx redocly lint
@@ -59,14 +59,14 @@ npx redocly lint
validating /openapi/openapi.yaml...
/openapi/openapi.yaml: validated in 39ms
Woohoo! Your OpenAPI definition is valid. 🎉
Woohoo! Your API description is valid. 🎉
```
Now you are ready to configure the rules.
## Case 1 - Single response containing one property
Imagine that your API definition describes users' data, and it should have `user_id` as a part of
Imagine that your API description describes users' data, and it should have `user_id` as a part of
all successful (`200`) responses. Let's define this.
1. Open the `.redocly.yaml` in the project folder
@@ -129,12 +129,12 @@ in the integrated terminal (Problems tab):
As you can see from the output, the rule triggered an error in the `200.yaml` file
indicating there is no `user_id` property for `200` responses.
Three "copies" of the error mean that there are three $refs within the OpenAPI definition
Three "copies" of the error mean that there are three $refs within the OpenAPI description
that refer to the `200` response schema object.
## Case 2 - Multiple responses containing one property
When you want to check that your OpenAPI definition contains property in all responses
When you want to check that your OpenAPI description contains property in all responses
of a specific [class](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes), you can use ranges.
Let's modify the previous example to check that all `2xx` responses contain the `user_id` property.
@@ -214,7 +214,7 @@ in the integrated terminal (Problems tab):
There are three `2xx` class responses defined for this guide, and you can see that the rule
has successfully triggered errors with the missing `user_id` property for all of them.
Yet, three $refs within the OpenAPI definition refer to the `200` response
Yet, three $refs within the OpenAPI description refer to the `200` response
schema object and one $ref refers to each of the `201` and `202` responses, resulting in
5 errors in total

2
docs/index.mdx
View File

@@ -19,7 +19,7 @@ Authenticate, update APIs, publish documentation, and use the other tools to man
Use open source <a href="https://github.com/redocly/redoc" target="_blank">Redoc</a> or our hosted tools to create clear and useful documentation with local previews and static builds available.
</WideTile>
<WideTile to="./file-management.md" header="Manage OpenAPI files">
Split an OpenAPI description into logical chunks, bundle the chunks to create a single file, or even join existing definitions into one.
Split an OpenAPI description into logical chunks, bundle the chunks to create a single file, or even join existing API descriptions into one.
</WideTile>
<WideTile to="./decorators.md" header="Transform OpenAPI">
Publish a subset of endpoints, or use decorators to enhance your existing OpenAPI by adding, changing, or removing content.

Some files were not shown because too many files have changed in this diff Show More