From 5a7f6960bb1da17da3d3eabf5a5f8f6328aacd98 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 18 Aug 2023 16:25:25 +0100 Subject: [PATCH 01/10] docs: Give Redoc a landing page with overview and tldr instructions --- docs/index.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..e4a45cf108 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,96 @@ +--- +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 based around a three panel layout, with clear sections for navigation, detailed documentation, and request/response examples. + +## Headline features + +* Modern layout with extensive customization options. +* Support for OpenAPI 3.1, 3.0 and older 2.0 and Swagger formats. +* Embed or build standalone HTML documentation. +* CLI tool for easy automation and local development. + +## Demo + +[Try the live demo](https://redocly.github.io/redoc/) and upload your own API specification there to try. + +## Usage + +Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component. + +### Generate documentation from the CLI + +If you have Node installed, quickly generate documentation using `npx`: + +``` +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. + +### Add an HTML element to the page + +Create an HTML page, or edit an existing one, and add the following: + +```html + + +``` + +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. + +### More usage options + +Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each. + +## Configure Redoc + +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. + +Here's a sample `redocly.yaml` configuration file, showing a few common settings and tweaking some of the visual theme settings: + +```yaml +theme: + openapi: + disableSearch: true + expandResponses: 200,202 + jsonSampleExpandLevel: 1 + + theme: + sidebar: + backgroundColor: '#eae0cc' + textColor: '#3d005b' + colors: + primary: + main: '#660099' + typography: + fontSize: 14pt + headings: + fontWeight: bold +``` + +Redocly CLI detects a file named `redocly.yaml` in the same directory as you run the command and uses it. See the documentation with a command like this: + +``` +redocly preview-docs openapi.yaml +``` + +There are many, many more options available. Visit the [configuration reference](./config.md) for a complete list. + +## 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). +* Learn more about the project by visiting [Redoc on GitHub](https://github.com/Redocly/redoc). From ff4dd3824db8faaaa711ab8bb37d7d33c8c93851 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 18 Aug 2023 20:39:09 +0100 Subject: [PATCH 02/10] docs: move config to dedicated page --- docs/config.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 docs/config.md diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000000..8889b0dc89 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,160 @@ +# Configure Redoc + +Getting your documentation just right is important, and Redoc comes with many configuration options to help you succeed in that mission. + +Each deployment type has documentation on how to options in its context. This page lists all the options you can use with Redoc. + +**Versions: 2.x** + +:::success Client-side configuration + +Using Redoc as a standalone (HTML or React) tool, these options must be presented in [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). +For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`. + +::: + +## Functional settings + +* `disableSearch` - disable search indexing and search box. +* `minCharacterLengthToInitSearch` - set minimal characters length to init search, default `3`, minimal `1`. +* `expandDefaultServerVariables` - enable expanding default server variables, default `false`. +* `expandResponses` - specify which responses to expand by default by response codes. Values should be passed as 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. +* `generatedPayloadSamplesMaxDepth` - set the maximum render depth for JSON payload samples (responses and request body). The default value is `10`. +* `maxDisplayedEnumValues` - display only specified number of enum values. hide rest values under spoiler. +* `hideDownloadButton` - do not show "Download" spec button. **THIS DOESN'T MAKE YOUR SPEC PRIVATE**, it just hides the button. +* `downloadFileName` - set a custom file name for the downloaded API definition file. +* `downloadDefinitionUrl` - If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here opens when that button is selected. Provide it as an absolute URL with the full URI scheme. +* `hideHostname` - if set, the protocol and hostname is not shown in the operation definition. +* `hideLoading` - do not show loading animation. Useful for small docs. +* `hideFab` - do not show FAB in mobile view. Useful for implementing a custom floating action button. +* `hideSchemaPattern` - if set, the pattern is not shown in the schema. +* `hideSingleRequestSampleTab` - do not show the request sample tab for requests with only one sample. +* `showObjectSchemaExamples` - show object schema example in the properties, default `false`. +* `expandSingleSchemaField` - automatically expand single field in a schema +* `schemaExpansionLevel` - specifies whether to automatically expand schemas. Special value `"all"` expands all levels. The default value is `0`. +* `jsonSampleExpandLevel` - set the default expand level for JSON payload samples (responses and request body). Special value `"all"` expands all levels. The default value is `2`. +* `hideSchemaTitles` - do not display schema `title` next to to the type +* `simpleOneOfTypeLabel` - show only unique oneOf types in the label without titles +* `sortEnumValuesAlphabetically` - set to true, sorts all enum values in all schemas alphabetically +* `sortOperationsAlphabetically` - set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically +* `sortTagsAlphabetically` - set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically +* `menuToggle` - if true, clicking second time on expanded menu item collapses it, default `true`. +* `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs). +* `onlyRequiredInSamples` - shows only required fields in request samples. +* `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one. +* `requiredPropsFirst` - show required properties first ordered in the same order as in `required` array. +* `scrollYOffset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc; +`scrollYOffset` can be specified in various ways: + * **number**: A fixed number of pixels to be used as offset. + * **selector**: selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as offset. + * **function**: A getter function. Must return a number representing the offset (in pixels). +* `showExtensions` - show vendor extensions ("x-" fields). Extensions used by Redoc are ignored. Can be boolean or an array of `string` with names of extensions to display. +* `sortPropsAlphabetically` - sort properties alphabetically. +* `payloadSampleIdx` - if set, payload sample is inserted at this index or last. Indexes start from 0. +* `theme` - Redoc theme. For details check [theme docs](#redoc-theme-object). +* `untrustedSpec` - if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. **Disabled by default** for performance reasons. **Enable this option if you work with untrusted user data!** +* `nonce` - if set, the provided value is injected in every injected HTML element in the `nonce` attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/. +* `sideNavStyle` - can be specified in various ways: + * **summary-only**: displays a summary in the sidebar navigation item. (**default**) + * **path-only**: displays a path in the sidebar navigation item. + * **id-only**: displays the operation id with a fallback to the path in the sidebar navigation item. +* `showWebhookVerb` - when set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar. + +## Theme object + +* `spacing` + * `unit`: 5 # main spacing unit used in autocomputed theme values later + * `sectionHorizontal`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8 + * `sectionVertical`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8 +* `breakpoints` # breakpoints for switching three/two and mobile view layouts + * `small`: '50rem' + * `medium`: '85rem' + * `large`: '105rem' +* `colors` + * `tonalOffset`: 0.3 # default tonal offset used in computations +* `typography` + * `fontSize`: '14px' + * `lineHeight`: '1.5em' + * `fontWeightRegular`: '400' + * `fontWeightBold`: '600' + * `fontWeightLight`: '300' + * `fontFamily`: 'Roboto, sans-serif' + * `smoothing`: 'antialiased' + * `optimizeSpeed`: true + * `headings` + * `fontFamily`: 'Montserrat, sans-serif' + * `fontWeight`: '400' + * `lineHeight`: '1.6em' + * `code` # inline code styling + * `fontSize`: '13px' + * `fontFamily`: 'Courier, monospace' + * `lineHeight`: # COMPUTED: typography.lineHeight + * `fontWeight`: # COMPUTED: typography.fontWeightRegular + * `color`: '#e53935' + * `backgroundColor`: 'rgba(38, 50, 56, 0.05)' + * `wrap`: false # whether to break word for inline blocks (otherwise they can overflow) + * `links` + * `color`: # COMPUTED: colors.primary.main + * `visited`: # COMPUTED: typography.links.color + * `hover`: # COMPUTED: lighten(0.2 typography.links.color) + * `textDecoration`: 'auto' + * `hoverTextDecoration`: 'auto' +* `sidebar` + * `width`: '260px' + * `backgroundColor`: '#fafafa' + * `textColor`: '#333333' + * `activeTextColor`: # COMPUTED: theme.sidebar.textColor (if set by user) or theme.colors.primary.main + * `groupItems` # Group headings + * `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor + * `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor + * `textTransform`: 'uppercase' + * `level1Items` # Level 1 items like tags or section 1st level items + * `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor + * `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor + * `textTransform`: 'none' + * `arrow` # sidebar arrow + * `size`: '1.5em' + * `color`: # COMPUTED: theme.sidebar.textColor +* `logo` + * `maxHeight`: # COMPUTED: sidebar.width + * `maxWidth`: # COMPUTED: sidebar.width + * `gutter`: '2px' # logo image padding +* `rightPanel` + * `backgroundColor`: '#263238' + * `width`: '40%' + * `textColor`: '#ffffff' + * `servers` + * `overlay` + * `backgroundColor`: '#fafafa' + * `textColor`: '#263238' + * `url` + * `backgroundColor`: '#fff' +* `fab` + * `backgroundColor`: '#263238' + * `color`: '#ffffff' + +## Additional customization + +### Security Definition location + +You can inject the Security Definitions widget into any place in your definition `description`. +For more information, refer to [Security definitions injection](./security-definitions-injection.md). + +### OpenAPI specification extensions + +Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/): +* [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo +* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc +* [`x-codeSamples`](docs/redoc-vendor-extensions.md#x-codeSamples) - specify operation code samples +* [`x-examples`](docs/redoc-vendor-extensions.md#x-examples) - specify JSON example for requests +* [`x-nullable`](docs/redoc-vendor-extensions.md#x-nullable) - mark schema param as a nullable +* [`x-displayName`](docs/redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories +* [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) - group tags by categories in the side menu +* [`x-servers`](docs/redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0) +* [`x-ignoredHeaderParameters`](docs/redoc-vendor-extensions.md#x-ignoredHeaderParameters) - ability to specify header parameter names to ignore +* [`x-additionalPropertiesName`](docs/redoc-vendor-extensions.md#x-additionalPropertiesName) - ability to supply a descriptive name for the additional property keys +* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - For Response object, use as the response button text, with description rendered under the button +* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator +* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object + + From 0eda284f29d70238424957034b0b101d92633e4d Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 18 Aug 2023 20:39:39 +0100 Subject: [PATCH 03/10] docs: modernise README, link to resources --- README.md | 327 +++++++++++++----------------------------------------- 1 file changed, 76 insertions(+), 251 deletions(-) diff --git a/README.md b/README.md index 9d50af9fd8..5a298cfb73 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,15 @@ # Generate interactive API documentation from OpenAPI definitions - [![Coverage Status](https://coveralls.io/repos/Redocly/redoc/badge.svg?branch=main&service=github)](https://coveralls.io/github/Redocly/redoc?branch=main) [![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/main/LICENSE) + [![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/main/LICENSE) - [![bundle size](http://img.badgesize.io/https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js?compression=gzip&max=300000)](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc) [![Docker Build Status](https://img.shields.io/docker/build/redocly/redoc.svg)](https://hub.docker.com/r/redocly/redoc/) + [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc) -**This is the README for the `2.x` version of Redoc (React-based).** -**The README for the `1.x` version is on the [v1.x](https://github.com/Redocly/redoc/tree/v1.x) branch.** ## About Redoc -Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions. +Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions. By default Redoc offers a three-panel, responsive layout: @@ -32,159 +30,91 @@ 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 vs. Reference vs. Portals +## Redoc Features -Redoc is Redocly's community-edition product. Looking for something more? -Checkout the following feature comparison of Redocly's premium products versus Redoc: - -| Features | Redoc | Reference | Portals | -|------------------------------|:---------:|:---------:|:-----------:| -| **Specs** | | | | -| Swagger 2.0 | √ | √ | √ | -| OpenAPI 3.0 | √ | √ | √ | -| OpenAPI 3.1 | √ (basic) | √ | √ | -| | | | | -| **Theming** | | | | -| Fonts/colors | √ | √ | √ | -| Extra theme options | | √ | √ | -| | | | | -| **Performance** | | | | -| Pagination | | √ | √ | -| Search (enhanced) | | √ | √ | -| Search (server-side) | | | √ | -| | | | | -| **Multiple APIs** | | | | -| Multiple versions | | √ | √ | -| Multiple APIs | | | √ | -| API catalog | | | √ | -| | | | | -| **Additional features** | | | | -| Try-it console | | √ | √ | -| Automated code samples | | √ | √ | -| Deep links | | √ | √ | -| More SEO control | | | √ | -| Contextual docs | | | √ | -| Landing pages | | | √ | -| React hooks for more control | | | √ | -| Personalization | | | √ | -| Analytics integrations | | | √ | -| Feedback | | | Coming Soon | - -Refer to the Redocly's documentation for more information on these products: - -- [Portals](https://redocly.com/docs/developer-portal/introduction/) -- [Reference](https://redocly.com/docs/api-reference-docs/getting-started/) -- [Redoc](https://redocly.com/docs/redoc/quickstart/intro/) - -## Features - Responsive three-panel design with menu/scrolling synchronization -- [Multiple deployment options](https://redocly.com/docs/redoc/quickstart/intro/) -- [Server-side rendering (SSR) ready](https://redocly.com/docs/redoc/quickstart/cli/#redoc-cli-commands) +- 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/) - - [Example repo](https://github.com/APIs-guru/create-react-app-redoc) -- [Command-line interface to bundle your docs into a **zero-dependency** HTML file](https://redocly.com/docs/cli/commands/build-docs/) -- Neat **interactive** documentation for nested objects
- ![](docs/images/nested-demo.gif) - -## Customization options -[Customization services](https://redocly.com/#services) -- High-level grouping in side-menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension -- Branding/customizations using the [`theme` option](https://redocly.com/docs/api-reference-docs/configuration/theming/) - -## Support -- OpenAPI v3.0 support -- Basic OpenAPI v3.1 support -- Broad OpenAPI v2.0 feature support (yes, it supports even `discriminator`)
- ![](docs/images/discriminator-demo.gif) - Code samples support (via vendor extension)
![](docs/images/code-samples-demo.gif) -## Releases -**Important:** all the 2.x releases are deployed to npm and can be used with Redocly-cdn: -- particular release, for example, `v2.0.0`: https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.js -- `latest` release: https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js +## Usage -Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**: -- particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js -- `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js -- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. +Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component. -## Version Guidance -| Redoc Release | OpenAPI Specification | -|:--------------|:----------------------| -| 2.0.0-alpha.54| 3.1, 3.0.x, 2.0 | -| 2.0.0-alpha.x | 3.0, 2.0 | -| 1.19.x | 2.0 | -| 1.18.x | 2.0 | -| 1.17.x | 2.0 | - -## Showcase -- [Rebilly](https://api-reference.rebilly.com/) -- [Docker Engine](https://docs.docker.com/engine/api/v1.25/) -- [Zuora](https://www.zuora.com/developer/api-reference/) -- [Discourse](http://docs.discourse.org) -- [Commbox](https://www.commbox.io/api/) -- [APIs.guru](https://apis.guru/api-doc/) -- [BoxKnight](https://www.docs.boxknight.com/) +### Generate documentation from the CLI -## Lint OpenAPI definitions +If you have Node installed, quickly generate documentation using `npx`: -Redocly CLI is an [open source command-line tool](https://github.com/Redocly/redocly-cli) that you can use to lint -your OpenAPI definition. Linting helps you to catch errors and inconsistencies in your -OpenAPI definition before publishing. +``` +npx @redocly/cli build-docs openapi.yaml +``` -Learn more about [API standards and linting](https://redocly.com/docs/cli/api-standards/) in the main Redocly documentation. +The tool outputs by default to a file named `redoc-static.html` that you can open in your browser. -## Deployment +> [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. -### TL;DR final code example +### Add an HTML element to the page -To render your OpenAPI definition using Redoc, use the following HTML code sample and -replace the `spec-url` attribute with the url or local file address to your definition. +Create an HTML page, or edit an existing one, and add the following: ```html - - - - Redoc - - - - - - - - - - + - - - ``` -For step-by-step instructions for how to get started using Redoc -to render your OpenAPI definition, refer to the -[**Redoc quickstart guide**](https://redocly.com/docs/redoc/quickstart/) and [**How to use the HTML element**](https://redocly.com/docs/redoc/deployment/html/). +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. + +### More usage options + +Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each. + + + +## Redoc vs. Reference + +Redoc is Redocly's community-edition product. Looking for something more? +We also offer [hosted API reference documentation](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/) +with additional features including: + +* Try-it console +* Automated code samples +* Pagination +* Extra theme options + +### Documentation and resources + +- [Reference docs](https://redocly.com/docs/api-reference-docs/getting-started/) - we take care of the hosting +- [Redoc](https://redocly.com/docs/redoc/) - detailed documentation for this open source project (also in the `docs/` folder) +- [Command-line interface to bundle your docs into a web-ready HTML file](https://redocly.com/docs/cli/commands/build-docs/) +- API linting, bundling, and much more with open source [Redocly CLI](https://redocly.com/docs/cli) + +## Showcase +A sample of the organisations using Redocly tools in the wild: + +- [Rebilly](https://api-reference.rebilly.com/) +- [Docker Engine](https://docs.docker.com/engine/api/v1.25/) +- [Zuora](https://www.zuora.com/developer/api-reference/) +- [Discourse](http://docs.discourse.org) +- [Commbox](https://www.commbox.io/api/) +- [APIs.guru](https://apis.guru/api-doc/) +- [BoxKnight](https://www.docs.boxknight.com/) + +_Pull requests to add your own API page to the list are welcome_ ## Configuration -### Security Definition location -You can inject the Security Definitions widget into any place in your definition `description`. -For more information, refer to [Security definitions injection](docs/security-definitions-injection.md). +Redoc is highly configurable, see the [configuration documentation](docs/config.md) for details. ### OpenAPI specification extensions Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/): + * [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo * [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc * [`x-codeSamples`](docs/redoc-vendor-extensions.md#x-codeSamples) - specify operation code samples @@ -199,126 +129,21 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api * [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator * [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object -### `` options object -You can use all of the following options with the standalone version of the tag by kebab-casing them. For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`. - -* `disableSearch` - disable search indexing and search box. -* `minCharacterLengthToInitSearch` - set minimal characters length to init search, default `3`, minimal `1`. -* `expandDefaultServerVariables` - enable expanding default server variables, default `false`. -* `expandResponses` - specify which responses to expand by default by response codes. Values should be passed as 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. -* `generatedPayloadSamplesMaxDepth` - set the maximum render depth for JSON payload samples (responses and request body). The default value is `10`. -* `maxDisplayedEnumValues` - display only specified number of enum values. hide rest values under spoiler. -* `hideDownloadButton` - do not show "Download" spec button. **THIS DOESN'T MAKE YOUR SPEC PRIVATE**, it just hides the button. -* `downloadFileName` - set a custom file name for the downloaded API definition file. -* `downloadDefinitionUrl` - If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here opens when that button is selected. Provide it as an absolute URL with the full URI scheme. -* `hideHostname` - if set, the protocol and hostname is not shown in the operation definition. -* `hideLoading` - do not show loading animation. Useful for small docs. -* `hideFab` - do not show FAB in mobile view. Useful for implementing a custom floating action button. -* `hideSchemaPattern` - if set, the pattern is not shown in the schema. -* `hideSingleRequestSampleTab` - do not show the request sample tab for requests with only one sample. -* `showObjectSchemaExamples` - show object schema example in the properties, default `false`. -* `expandSingleSchemaField` - automatically expand single field in a schema -* `schemaExpansionLevel` - specifies whether to automatically expand schemas. Special value `"all"` expands all levels. The default value is `0`. -* `jsonSampleExpandLevel` - set the default expand level for JSON payload samples (responses and request body). Special value `"all"` expands all levels. The default value is `2`. -* `hideSchemaTitles` - do not display schema `title` next to to the type -* `simpleOneOfTypeLabel` - show only unique oneOf types in the label without titles -* `sortEnumValuesAlphabetically` - set to true, sorts all enum values in all schemas alphabetically -* `sortOperationsAlphabetically` - set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically -* `sortTagsAlphabetically` - set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically -* `menuToggle` - if true, clicking second time on expanded menu item collapses it, default `true`. -* `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs). -* `onlyRequiredInSamples` - shows only required fields in request samples. -* `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one. -* `requiredPropsFirst` - show required properties first ordered in the same order as in `required` array. -* `scrollYOffset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc; -`scrollYOffset` can be specified in various ways: - * **number**: A fixed number of pixels to be used as offset. - * **selector**: selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as offset. - * **function**: A getter function. Must return a number representing the offset (in pixels). -* `showExtensions` - show vendor extensions ("x-" fields). Extensions used by Redoc are ignored. Can be boolean or an array of `string` with names of extensions to display. -* `sortPropsAlphabetically` - sort properties alphabetically. -* `payloadSampleIdx` - if set, payload sample is inserted at this index or last. Indexes start from 0. -* `theme` - Redoc theme. For details check [theme docs](#redoc-theme-object). -* `untrustedSpec` - if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. **Disabled by default** for performance reasons. **Enable this option if you work with untrusted user data!** -* `nonce` - if set, the provided value is injected in every injected HTML element in the `nonce` attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/. -* `sideNavStyle` - can be specified in various ways: - * **summary-only**: displays a summary in the sidebar navigation item. (**default**) - * **path-only**: displays a path in the sidebar navigation item. - * **id-only**: displays the operation id with a fallback to the path in the sidebar navigation item. -* `showWebhookVerb` - when set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar. - -### `` theme object -* `spacing` - * `unit`: 5 # main spacing unit used in autocomputed theme values later - * `sectionHorizontal`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8 - * `sectionVertical`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8 -* `breakpoints` # breakpoints for switching three/two and mobile view layouts - * `small`: '50rem' - * `medium`: '85rem' - * `large`: '105rem' -* `colors` - * `tonalOffset`: 0.3 # default tonal offset used in computations -* `typography` - * `fontSize`: '14px' - * `lineHeight`: '1.5em' - * `fontWeightRegular`: '400' - * `fontWeightBold`: '600' - * `fontWeightLight`: '300' - * `fontFamily`: 'Roboto, sans-serif' - * `smoothing`: 'antialiased' - * `optimizeSpeed`: true - * `headings` - * `fontFamily`: 'Montserrat, sans-serif' - * `fontWeight`: '400' - * `lineHeight`: '1.6em' - * `code` # inline code styling - * `fontSize`: '13px' - * `fontFamily`: 'Courier, monospace' - * `lineHeight`: # COMPUTED: typography.lineHeight - * `fontWeight`: # COMPUTED: typography.fontWeightRegular - * `color`: '#e53935' - * `backgroundColor`: 'rgba(38, 50, 56, 0.05)' - * `wrap`: false # whether to break word for inline blocks (otherwise they can overflow) - * `links` - * `color`: # COMPUTED: colors.primary.main - * `visited`: # COMPUTED: typography.links.color - * `hover`: # COMPUTED: lighten(0.2 typography.links.color) - * `textDecoration`: 'auto' - * `hoverTextDecoration`: 'auto' -* `sidebar` - * `width`: '260px' - * `backgroundColor`: '#fafafa' - * `textColor`: '#333333' - * `activeTextColor`: # COMPUTED: theme.sidebar.textColor (if set by user) or theme.colors.primary.main - * `groupItems` # Group headings - * `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor - * `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor - * `textTransform`: 'uppercase' - * `level1Items` # Level 1 items like tags or section 1st level items - * `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor - * `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor - * `textTransform`: 'none' - * `arrow` # sidebar arrow - * `size`: '1.5em' - * `color`: # COMPUTED: theme.sidebar.textColor -* `logo` - * `maxHeight`: # COMPUTED: sidebar.width - * `maxWidth`: # COMPUTED: sidebar.width - * `gutter`: '2px' # logo image padding -* `rightPanel` - * `backgroundColor`: '#263238' - * `width`: '40%' - * `textColor`: '#ffffff' - * `servers` - * `overlay` - * `backgroundColor`: '#fafafa' - * `textColor`: '#263238' - * `url` - * `backgroundColor`: '#fff' -* `fab` - * `backgroundColor`: '#263238' - * `color`: '#ffffff' - ----------- + +## Releases + +**The README for the `1.x` version is on the [v1.x](https://github.com/Redocly/redoc/tree/v1.x) branch.** + +All the 2.x releases are deployed to npm and can be used with Redocly-cdn: +- particular release, for example, `v2.0.0`: https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.js +- `latest` release: https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js + +Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**: +- particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js +- `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js +- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. + + ## Development see [CONTRIBUTING.md](.github/CONTRIBUTING.md) From 7324afdc6b77a0382be2257346baf01a2c06515b Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Wed, 23 Aug 2023 11:44:39 +0100 Subject: [PATCH 04/10] docs: more detailed format for theme configurations --- docs/config.md | 198 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 152 insertions(+), 46 deletions(-) diff --git a/docs/config.md b/docs/config.md index 8889b0dc89..95ef98a4d9 100644 --- a/docs/config.md +++ b/docs/config.md @@ -15,52 +15,158 @@ For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` be ## Functional settings -* `disableSearch` - disable search indexing and search box. -* `minCharacterLengthToInitSearch` - set minimal characters length to init search, default `3`, minimal `1`. -* `expandDefaultServerVariables` - enable expanding default server variables, default `false`. -* `expandResponses` - specify which responses to expand by default by response codes. Values should be passed as 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. -* `generatedPayloadSamplesMaxDepth` - set the maximum render depth for JSON payload samples (responses and request body). The default value is `10`. -* `maxDisplayedEnumValues` - display only specified number of enum values. hide rest values under spoiler. -* `hideDownloadButton` - do not show "Download" spec button. **THIS DOESN'T MAKE YOUR SPEC PRIVATE**, it just hides the button. -* `downloadFileName` - set a custom file name for the downloaded API definition file. -* `downloadDefinitionUrl` - If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here opens when that button is selected. Provide it as an absolute URL with the full URI scheme. -* `hideHostname` - if set, the protocol and hostname is not shown in the operation definition. -* `hideLoading` - do not show loading animation. Useful for small docs. -* `hideFab` - do not show FAB in mobile view. Useful for implementing a custom floating action button. -* `hideSchemaPattern` - if set, the pattern is not shown in the schema. -* `hideSingleRequestSampleTab` - do not show the request sample tab for requests with only one sample. -* `showObjectSchemaExamples` - show object schema example in the properties, default `false`. -* `expandSingleSchemaField` - automatically expand single field in a schema -* `schemaExpansionLevel` - specifies whether to automatically expand schemas. Special value `"all"` expands all levels. The default value is `0`. -* `jsonSampleExpandLevel` - set the default expand level for JSON payload samples (responses and request body). Special value `"all"` expands all levels. The default value is `2`. -* `hideSchemaTitles` - do not display schema `title` next to to the type -* `simpleOneOfTypeLabel` - show only unique oneOf types in the label without titles -* `sortEnumValuesAlphabetically` - set to true, sorts all enum values in all schemas alphabetically -* `sortOperationsAlphabetically` - set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically -* `sortTagsAlphabetically` - set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically -* `menuToggle` - if true, clicking second time on expanded menu item collapses it, default `true`. -* `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs). -* `onlyRequiredInSamples` - shows only required fields in request samples. -* `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one. -* `requiredPropsFirst` - show required properties first ordered in the same order as in `required` array. -* `scrollYOffset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc; -`scrollYOffset` can be specified in various ways: - * **number**: A fixed number of pixels to be used as offset. - * **selector**: selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as offset. - * **function**: A getter function. Must return a number representing the offset (in pixels). -* `showExtensions` - show vendor extensions ("x-" fields). Extensions used by Redoc are ignored. Can be boolean or an array of `string` with names of extensions to display. -* `sortPropsAlphabetically` - sort properties alphabetically. -* `payloadSampleIdx` - if set, payload sample is inserted at this index or last. Indexes start from 0. -* `theme` - Redoc theme. For details check [theme docs](#redoc-theme-object). -* `untrustedSpec` - if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. **Disabled by default** for performance reasons. **Enable this option if you work with untrusted user data!** -* `nonce` - if set, the provided value is injected in every injected HTML element in the `nonce` attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/. -* `sideNavStyle` - can be specified in various ways: - * **summary-only**: displays a summary in the sidebar navigation item. (**default**) - * **path-only**: displays a path in the sidebar navigation item. - * **id-only**: displays the operation id with a fallback to the path in the sidebar navigation item. -* `showWebhookVerb` - when set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar. - -## Theme object + +### disableSearch + +Disables search indexing and hides the search box from the API documentation page. + +### minCharacterLengthToInitSearch + +Sets the minimum amount of characters that need to be typed into the search dialog to initiate the search. + +_Default: 3_ + +### expandDefaultServerVariables + +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. + +### expandSingleSchemaField + +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. + +### hideHostname + +If set to `true`, the protocol and hostname are not shown in the operation definition. + +### hideLoading + +Hides the loading animation. Does not apply to CLI or Workflows-rendered docs. + +### hideRequestPayloadSample + +Hides request payload examples. + +### hideOneOfDescription + +If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema. + +### hideSchemaPattern + +If set to `true`, the pattern is not shown in the schema. + +### hideSchemaTitles + +Hides the schema title next to to the type. + +### hideSecuritySection + +Hides the Security panel section. + +### hideSingleRequestSampleTab + +Hides the request sample tab for requests with only one sample. + +### htmlTemplate + +Sets the path to the optional HTML file used to modify the layout of the reference docs page. + +### jsonSampleExpandLevel + +Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels. + +_Default: 2_ + +### maxDisplayedEnumValues + +Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed. + +### menuToggle + +If set to `true`, selecting an expanded item in the sidebar twice will collapse it. + +_Default: true_ + +### nativeScrollbars + +If set to `true`, the sidebar will use the native scrollbar instead of perfect-scroll. This is a scrolling performance optimization for big API definitions. + +### onlyRequiredInSamples + +Shows only required fields in request samples. + +### pathInMiddlePanel + +Shows the path link and HTTP verb in the middle panel instead of the right panel. + +### payloadSampleIdx + +If set, the payload sample will be inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample will be inserted last. Indexes start from 0. + +### requiredPropsFirst + +Shows required properties in schemas first, ordered in the same order as in required array. + +### schemaExpansionLevel + +Specifies whether to automatically expand schemas in Reference docs. Set it to `all` to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, `schemaExpansionLevel: 3` expands schemas up to three levels deep. The default value is `0`, meaning no schemas are expanded automatically. + +### 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. + +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. +- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom will be used as the offset. +- a function (advanced) - a getter function. Must return a number representing the offset (in pixels). + +### showExtensions + +Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to `true`, all specification extensions are shown. + +### showObjectSchemaExamples + +Show object schema example in the properties, default false. + +### showWebhookVerb + +When set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar. + +### simpleOneOfTypeLabel + +Shows only unique `oneOf` types in the label without titles. + +### sortEnumValuesAlphabetically + +When set to `true`, sorts all enum values in all schemas alphabetically. + +### sortOperationsAlphabetically + +When set to `true`, sorts operations in the navigation sidebar and in the middle panel alphabetically. + +### sortPropsAlphabetically + +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 will be 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. + +_Default: false_ + +### untrustedDefinition + +If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS. + +## Theme settings * `spacing` * `unit`: 5 # main spacing unit used in autocomputed theme values later From e1f5b84f3a828ae7361fb885265d49e946d4afa8 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Wed, 23 Aug 2023 11:46:44 +0100 Subject: [PATCH 05/10] fix: README formatting --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 5a298cfb73..ac119085eb 100644 --- a/README.md +++ b/README.md @@ -74,8 +74,6 @@ Add your own `spec-url` to the `` tag, this attribute can also be a local Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each. - - ## Redoc vs. Reference Redoc is Redocly's community-edition product. Looking for something more? @@ -129,8 +127,6 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api * [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator * [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object ------------ - ## Releases **The README for the `1.x` version is on the [v1.x](https://github.com/Redocly/redoc/tree/v1.x) branch.** From 154e8af8bddd24bcab62806bffaea77d43b708fe Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 1 Sep 2023 15:57:11 +0100 Subject: [PATCH 06/10] fix: Fix future tense errors and add exceptions for config fields as headings --- .github/styles/Rules/HeaderGerunds.yml | 4 ++++ docs/config.md | 10 +++++----- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/styles/Rules/HeaderGerunds.yml b/.github/styles/Rules/HeaderGerunds.yml index 5f5930708a..ae3650bad4 100644 --- a/.github/styles/Rules/HeaderGerunds.yml +++ b/.github/styles/Rules/HeaderGerunds.yml @@ -5,3 +5,7 @@ level: error scope: heading tokens: - '^\w*ing.*' +exceptions: + - expandSingleSchemaField + - hideLoading + - hideSingleRequestSampleTab diff --git a/docs/config.md b/docs/config.md index 95ef98a4d9..93713cfe63 100644 --- a/docs/config.md +++ b/docs/config.md @@ -90,13 +90,13 @@ Displays only the specified number of enum values. The remaining values are hidd ### menuToggle -If set to `true`, selecting an expanded item in the sidebar twice will collapse it. +If set to `true`, selecting an expanded item in the sidebar twice collapses it. _Default: true_ ### nativeScrollbars -If set to `true`, the sidebar will use 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 is a scrolling performance optimization for big API definitions. ### onlyRequiredInSamples @@ -108,7 +108,7 @@ Shows the path link and HTTP verb in the middle panel instead of the right panel ### payloadSampleIdx -If set, the payload sample will be inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample will be inserted last. Indexes start from 0. +If set, the payload sample is inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample is inserted last. Indexes start from 0. ### requiredPropsFirst @@ -125,7 +125,7 @@ This is useful when there are fixed positioned elements at the top of the page, 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. -- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom will be used as the offset. +- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset. - a function (advanced) - a getter function. Must return a number representing the offset (in pixels). ### showExtensions @@ -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 will be 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 sortOperationsAlphabetically to true. _Default: false_ From 8151d690ef51e65c14758297bcef32b89bd55c35 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 4 Sep 2023 17:53:18 +0100 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Heather Cloward --- README.md | 14 +++++++------- docs/config.md | 14 +++++++------- docs/index.md | 8 ++++---- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ac119085eb..1cffb8b6e1 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 93713cfe63..927bde1094 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 e4a45cf108..768c3ad2ff 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). From e97da28f3cb489073bea7d97686a99a381478482 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Mon, 4 Sep 2023 18:08:57 +0100 Subject: [PATCH 08/10] docs: minor updates from excellent pull request feedback --- README.md | 13 +++++++------ docs/config.md | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1cffb8b6e1..9c39717aaf 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/main/LICENSE) - [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc) + [![bundle size](http://img.badgesize.io/https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js?compression=gzip&max=300000)](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc) @@ -35,8 +35,9 @@ enter the URL for your definition and select **TRY IT**. - Responsive three-panel design with menu/scrolling synchronization - 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 +- Interactive interface so your users can try the API immediately - Ability to integrate your API introduction into the side menu +- High-level grouping in side menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension - [Simple integration with `create-react-app`](https://redocly.com/docs/redoc/quickstart/react/) - Code samples support (with vendor extension)
![](docs/images/code-samples-demo.gif) @@ -114,7 +115,7 @@ Redoc is highly configurable, see the [configuration documentation](docs/config. Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/): * [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo -* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc +* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for tags that refer to non-navigation properties like Pagination, Rate-Limits, etc * [`x-codeSamples`](docs/redoc-vendor-extensions.md#x-codeSamples) - specify operation code samples * [`x-examples`](docs/redoc-vendor-extensions.md#x-examples) - specify JSON example for requests * [`x-nullable`](docs/redoc-vendor-extensions.md#x-nullable) - mark schema param as a nullable @@ -123,9 +124,9 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api * [`x-servers`](docs/redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0) * [`x-ignoredHeaderParameters`](docs/redoc-vendor-extensions.md#x-ignoredHeaderParameters) - ability to specify header parameter names to ignore * [`x-additionalPropertiesName`](docs/redoc-vendor-extensions.md#x-additionalPropertiesName) - ability to supply a descriptive name for the additional property keys -* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - For Response object, use as the response button text, with description rendered under the button -* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator -* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object +* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - for Response object, use as the response button text, with description rendered under the button +* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - in Schemas, uses this to solve name-clash issues with the standard discriminator +* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object ## Releases diff --git a/docs/config.md b/docs/config.md index 927bde1094..411f91d644 100644 --- a/docs/config.md +++ b/docs/config.md @@ -2,7 +2,7 @@ Getting your documentation just right is important, and Redoc comes with many configuration options to help you succeed in that mission. -Each deployment type has documentation on how to options in its context. This page lists all the options you can use with Redoc. +Each deployment type has documentation on how to configure options for that type of Redoc project. This page lists all the options you can use with Redoc. **Versions: 2.x** From 9658ad42a5fc70fe6e4d1d438ef84c2b915e196c Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Mon, 18 Sep 2023 14:47:10 +0100 Subject: [PATCH 09/10] docs: Remove the old quickstart, update HTML as the preferred onboarding method and improve docs/examples on that page --- docs/deployment/html.md | 173 ++++++++++++++++++++++------------------ docs/quickstart.md | 54 ------------- 2 files changed, 97 insertions(+), 130 deletions(-) delete mode 100644 docs/quickstart.md diff --git a/docs/deployment/html.md b/docs/deployment/html.md index dd7d649369..65c18693a1 100644 --- a/docs/deployment/html.md +++ b/docs/deployment/html.md @@ -1,123 +1,144 @@ --- -title: Use the Redoc HTML element +title: Use Redoc in HTML redirectFrom: - /docs/redoc/quickstart/html/ + - /docs/redoc/quickstart/ --- -# How to use the Redoc HTML element +# Use Redoc in HTML -## Step 1 - Install Redoc +To render API documentation in an HTML page, start with the template below and +replace the `spec-url` value with the local file path or URL of your API +description. -You can install Redoc using one of the following package managers: +```html + + + + Redoc + + + + + + + + + + + + + +``` -- [npm](https://docs.npmjs.com/about-npm) -- [yarn](https://classic.yarnpkg.com/en/docs/getting-started) +:::Success URL or local file -:::attention Initialize your package manager -If you do not have a `package.json` file in your project directory, -you need to add one by initializing npm or yarn in your project. Use the command `npm init` for npm, -or `yarn init` for yarn. These initialization commands lead you through the process -of creating a `package.json` file in your project. +Set `spec-url` to a relative path if the file is local, e.g. `spec-url=my-api.yaml`. Use a full URL like the example above if it's hosted elsewhere. -For more information, see -[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file) -in the npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/) -in the yarn documentation. ::: -### Install Redoc with yarn +Open the HTML file in your browser to see the HTML documentation rendering. You may want to read the next section and add some configuration to make your documentation your own. -After navigating to your project directory in your terminal, use the following command: +## Configure Redoc -```bash -yarn add redoc -``` +Redoc is highly configurable, find a [full list of configuration options](../config.md) on the dedicated page. -### Install Redoc with npm +To configure Redoc in HTML, add the property names to the HTML tag. Here's an example that makes all the required properties display first in the list: -After navigating to your project directory in your terminal, use the following command: - -```bash -npm i redoc +```html + ``` -## Step 2 - Reference the Redoc script +Any of the individual properties can be added to the tag, as many as you need to get your API docs set up as you like them. -You can reference the Redoc script using either a link to the files hosted on a CDN -or the files located in your `node modules` folder. - -### CDN link +### Theme configuration -To reference the Redoc script with a CDN link: +The `theme` configuration setting is more complex since it represents many nested options, you can supply these as a JSON string to the `theme` attribute. For example, to change the sidebar color you would use a tag like this: ```html - + ``` -### Node modules link +Check out the [list of options for theme configuration](../config.md#theme-settings) and build up the configuration that suits your API needs. -To reference the Redoc script with a node modules link: +## Advanced options -```html - -``` - -## Step 3 - Add the element - -You can add the element to your HTML page and reference your OpenAPI -definition using the `spec-url` attribute, or you can initialize Redoc using -a globally exposed Redoc object. +### The Redoc object -### The `spec-url` attribute +As an alternative to the HTML tag, you can also initialise Redoc in a web page using the Redoc object and invoking it from JavaScript. This is useful for situations where you want to create dynamic content in a page, and also provides a simple way to attach the Redoc element to an existing container. -To add the element with the `spec-url` attribute: +The Redoc object offers an `init` function: -```html - +```js +Redoc.init(specOrSpecUrl, options, element, callback) ``` +- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a file name/URL to the + definition in JSON or YAML format. +- `options`: See the [configuration reference](../config.md). +- `element`: DOM element Redoc is inserted into. +- `callback`(optional): Callback to be called after Redoc has been fully rendered. + It is also called on errors with `error` as the first argument. -#### Examples +Call `Redoc.init()` from the JavaScript on a web page to add the element to the named container. Below is an example of an HTML page with a `
` tag, and the JavaScript to add the Redoc object to it. ```html - + + + + +

Redoc in action

+ +
+ + + + ``` -You can also use a local file (JSON or YAML) in your project, for instance: +This example also sets the configuration for `expandResponses` so all 200 and 400 status responses are shown unfolded and with their details visible when the page loads. -```html - -``` +### Self-host dependencies -### The Redoc object +You can reference the Redoc script using either a link to the files hosted on a CDN +or install to your `node-modules` folder. Using the CDN is the simplest option, but +if you need to host in a closed environment or have requirements around external +dependencies, it may be useful to self-host. -To add the element with a globally exposed Redoc object: +The main example shows using the CDN: -```js -Redoc.init(specOrSpecUrl, options, element, callback) +```html + ``` -- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a URL to the - definition in JSON or YAML format. -- `options`: See [`theme.openapi` object](/docs/api-reference-docs/configuration/functionality.mdx) reference. -- `element`: DOM element Redoc is inserted into. -- `callback`(optional): Callback to be called after Redoc has been fully rendered. - It is also called on errors with `error` as the first argument. -#### Examples +If you would instead prefer to host the depdencies yourself, first install `redoc` using `npm`: -```html - ``` +npm install redoc +``` + +_(Yarn users can install the `redoc` package with `yarn`)_. -You can also use a local file (JSON or YAML) in your project, for instance: +You can then reference the Redoc script with a node modules link: ```html - + ``` + diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index 1b01e0f11e..0000000000 --- a/docs/quickstart.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Redoc quickstart guide ---- - -# Redoc quickstart guide - -To render your OpenAPI definition using Redoc, use the following HTML code sample and -replace the `spec-url` attribute with the URL or local file address to your definition. - -```html - - - - Redoc - - - - - - - - - - - - - - - -``` - -:::attention Redoc requires an HTTP server to run locally - -Loading local OpenAPI definitions is impossible without running a web server because of issues with -[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and -other security reasons. Refer to [Running Redoc locally](./deployment/intro.md#how-to-run-redoc-locally) for more information. - -::: - -For a more detailed explanation with step-by-step instructions and additional options for using Redoc, refer to the [Redoc deployment guide](./deployment/intro.md). From 7c41ac332eee510b5c0c432e3084c502d74be775 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 18 Sep 2023 14:52:09 +0100 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Heather Cloward --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9c39717aaf..8eca400f15 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ 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