diff --git a/README.md b/README.md index ac119085..1cffb8b6 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,15 @@ A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your definition and select **TRY IT**. -## Redoc Features +## Redoc features - Responsive three-panel design with menu/scrolling synchronization -- Support for OpenAPI 3.1, OpenAPI 3.0 and Swagger 2.0 +- Support for OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0 - [Multiple deployment options](https://redocly.com/docs/redoc/) - High-level grouping in side menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension - Ability to integrate your API introduction into the side menu - [Simple integration with `create-react-app`](https://redocly.com/docs/redoc/quickstart/react/) -- Code samples support (via vendor extension)
+- Code samples support (with vendor extension)
![](docs/images/code-samples-demo.gif) ## Usage @@ -55,11 +55,11 @@ npx @redocly/cli build-docs openapi.yaml The tool outputs by default to a file named `redoc-static.html` that you can open in your browser. -> [Redocly CLI](https://github.com/Redocly/redocly-cli/) does more than docs, check it out and add linting, bundling and more to your API workflow. +> [Redocly CLI](https://github.com/Redocly/redocly-cli/) does more than docs, check it out and add linting, bundling, and more to your API workflow. ### Add an HTML element to the page -Create an HTML page, or edit an existing one, and add the following: +Create an HTML page, or edit an existing one, and add the following within the body tags: ```html @@ -68,7 +68,7 @@ Create an HTML page, or edit an existing one, and add the following: Open the HTML file in your browser, and your API documentation is shown on the page. -Add your own `spec-url` to the `` tag, this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details. +Add your own `spec-url` to the `` tag; this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details. ### More usage options @@ -94,7 +94,7 @@ with additional features including: ## Showcase -A sample of the organisations using Redocly tools in the wild: +A sample of the organizations using Redocly tools in the wild: - [Rebilly](https://api-reference.rebilly.com/) - [Docker Engine](https://docs.docker.com/engine/api/v1.25/) diff --git a/docs/config.md b/docs/config.md index 93713cfe..927bde10 100644 --- a/docs/config.md +++ b/docs/config.md @@ -32,7 +32,7 @@ Enables or disables expanding default server variables. ### expandResponses -Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, e.g. `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time. +Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time. ### expandSingleSchemaField @@ -40,7 +40,7 @@ Automatically expands the single field in a schema. ### hideDownloadButton -Hides the 'Download' button for saving the API definition source file. **This does not make the API definition private**, it just hides the button. +Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button. ### hideHostname @@ -96,7 +96,7 @@ _Default: true_ ### nativeScrollbars -If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This is a scrolling performance optimization for big API definitions. +If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions. ### onlyRequiredInSamples @@ -112,7 +112,7 @@ If set, the payload sample is inserted at the specified index. If there are `N` ### requiredPropsFirst -Shows required properties in schemas first, ordered in the same order as in required array. +Shows required properties in schemas first, ordered in the same order as in the required array. ### schemaExpansionLevel @@ -121,7 +121,7 @@ Specifies whether to automatically expand schemas in Reference docs. Set it to ` ### scrollYOffset Specifies a vertical scroll-offset. -This is useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc. +This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc. Note that you can specify the `scrollYOffset` value in any of the following ways: - as a number - a fixed number of pixels to be used as the offset. @@ -134,7 +134,7 @@ Shows specification extensions ('x-' fields). Extensions used by Redoc are ignor ### showObjectSchemaExamples -Show object schema example in the properties, default false. +Shows object schema example in the properties; default `false`. ### showWebhookVerb @@ -158,7 +158,7 @@ When set to `true`, sorts properties in all schemas alphabetically. ### sortTagsAlphabetically -When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags are sorted alphabetically in the middle panel, not the operations associated with each tag. To sort operations alphabetically as well, you must set sortOperationsAlphabetically to true. +When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags are sorted alphabetically in the middle panel, not the operations associated with each tag. To sort operations alphabetically as well, you must set the `sortOperationsAlphabetically` setting to `true`. _Default: false_ diff --git a/docs/index.md b/docs/index.md index e4a45cf1..768c3ad2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ title: Redoc # Redoc: Open source API documentation tool -Redoc is a clean and easy way to produce web-ready documentation from an OpenAPI description (Swagger is also still supported). With one command, create your documentation, and customise it to meet the needs of your users. +Redoc is a clean and easy way to produce web-ready documentation from an OpenAPI description (Swagger is also still supported). With one command, create your documentation, and customize it to meet the needs of your users. Redoc is based around a three panel layout, with clear sections for navigation, detailed documentation, and request/response examples. @@ -46,7 +46,7 @@ Create an HTML page, or edit an existing one, and add the following: Open the HTML file in your browser, and your API documentation is shown on the page. -Add your own `spec-url` to the `` tag, this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details. +Add your own `spec-url` to the `` tag; this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details. ### More usage options @@ -57,7 +57,7 @@ Check out the [deployment documentation](./deploment/index/md) for more options, Redoc is highly configurable. Each deployment option accepts configuration in a way that's appropriate to that platform, but the options are the same for each. For example: * Using [Redocly CLI](../cli/index.md), configuration goes in the `redocly.yaml` file, or can be supplied as command line parameters, such as `--theme.openapi.disableSearch`. -* Using HTML or React or react, configure by setting `option` in the tag. +* Using HTML or React, configure by setting `option` in the tag. Here's a sample `redocly.yaml` configuration file, showing a few common settings and tweaking some of the visual theme settings: @@ -92,5 +92,5 @@ There are many, many more options available. Visit the [configuration reference] ## Next steps * If you are new to OpenAPI, try the [OpenAPI starter project](../../cli/openapi-starter/) for a great introduction. -* Ready to build documentation from an existing OpenAPI file? The [Redoc quickstart](./quickstart.md). +* Ready to build documentation from an existing OpenAPI file? Go to the [Redoc quickstart](./quickstart.md) and get started. * Learn more about the project by visiting [Redoc on GitHub](https://github.com/Redocly/redoc).