From f8925facf822f9bdb1cb2d3d14aea644d4e2840f Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sun, 12 Sep 2021 21:41:29 -0400 Subject: [PATCH 1/8] Updates readme with about section and organizes features list --- README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 76 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 855dac49be..9ed57fa80c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@
ReDoc logo - **OpenAPI/Swagger-generated API Reference Documentation** + # Generate interactive API documentation from OpenAPI definitions [![Build Status](https://travis-ci.com/Redocly/redoc.svg?branch=master)](https://travis-ci.com/Redocly/redoc) [![Coverage Status](https://coveralls.io/repos/Redocly/redoc/badge.svg?branch=master&service=github)](https://coveralls.io/github/Redocly/redoc?branch=master) [![dependencies Status](https://david-dm.org/Redocly/redoc/status.svg)](https://david-dm.org/Redocly/redoc) [![devDependencies Status](https://david-dm.org/Redocly/redoc/dev-status.svg)](https://david-dm.org/Redocly/redoc#info=devDependencies) [![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/master/LICENSE) @@ -11,30 +11,60 @@ **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 OpenAPI(aka Swagger) definitions. By default +Redoc offers a three-panel, responsive layout: the left panel contains a search bar and navigation menu, +the central panel contains the documentation, and the right panel contains request and response +examples. + ![ReDoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) -## [Live demo](http://redocly.github.io/redoc/) +## Live demo + +If you want to see how ReDoc will render your OpenAPI definition, +you can try it out online at https://redocly.github.io/redoc/. + +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. Redocly Reference docs + +Redoc Community Edition is free open-source software (OSS). +Redocly has developed extensive enhancements on top of Redoc Community Edition's open core, creating Redocly Reference Docs. +See [Comparison Redoc CE vs. Redocly Reference Docs](https://redoc.ly/redoc-vs-reference/) +for the main differences between the Redoc Community Edition and Redocly Reference Docs. + +## Deploy to GitHub +[Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) -[Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) [ReDoc as a service](https://redoc.ly) [Customization services](https://redoc.ly/#services) +## Redoc as a service +[Redoc as a service](https://redoc.ly/workflows) ## Features +- Responsive three-panel design with menu/scrolling synchronization - [Multiple deployment options](https://redoc.ly/docs/redoc/quickstart/intro/) +- Deep linking support - [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/quickstart/cli/#redoc-cli-commands) +- Ability to integrate your API introduction into the side menu - [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/quickstart/react/) - - [See an example](https://github.com/APIs-guru/create-react-app-redoc) + + [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://redoc.ly/docs/redoc/quickstart/cli/) -- Responsive three-panel design with menu/scrolling synchronization -- Deep linking support -- Ability to integrate your API introduction into the side menu -- High-level grouping in side-menu with [`x-tagGroups`](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension +- Neat **interactive** documentation for nested objects
+ ![](docs/images/nested-demo.gif) + +## Customization options +[Customization services](https://redoc.ly/#services) +- High-level grouping in side-menu with the [`x-tagGroups`](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension - Branding/customizations using the [`theme` option](https://redoc.ly/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) -- Neat **interactive** documentation for nested objects
- ![](docs/images/nested-demo.gif) - Code samples support (via vendor extension)
![](docs/images/code-samples-demo.gif) @@ -44,7 +74,7 @@ - `next` release: https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**: -- particular release, e.g. `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js +- 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 - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. @@ -67,15 +97,46 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d - [BoxKnight](https://www.docs.boxknight.com/) ## Deployment + +### TL;DR final code example + +```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://redoc.ly/docs/redoc/quickstart/intro/). +[**Redoc quickstart guide**](https://redoc.ly/docs/redoc/quickstart/intro/). -[**IE11 Support Notes**](docs/usage-with-ie11.md) +See [**IE11 Support Notes**](docs/usage-with-ie11.md) for information on ## ReDoc CLI For more information on Redoc's commmand-line interface, refer to -[Using the Redoc CLI](https://redoc.ly/docs/redoc/quickstart/cli/). +[**Using the Redoc CLI**](https://redoc.ly/docs/redoc/quickstart/cli/). ## Configuration From 899d7f9637815619d708ef8cfd1078b6339bfe61 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Mon, 13 Sep 2021 07:22:18 -0400 Subject: [PATCH 2/8] Adds some notes to deployment --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 9ed57fa80c..5647e2fdc9 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,9 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d ### TL;DR final code example +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 @@ -133,6 +136,7 @@ to render your OpenAPI definition, refer to the [**Redoc quickstart guide**](https://redoc.ly/docs/redoc/quickstart/intro/). See [**IE11 Support Notes**](docs/usage-with-ie11.md) for information on +IE support for Redoc. ## ReDoc CLI For more information on Redoc's commmand-line interface, refer to From c87600d520f037d291169b44b5803a35af16b5a5 Mon Sep 17 00:00:00 2001 From: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com> Date: Tue, 21 Sep 2021 22:17:48 +0200 Subject: [PATCH 3/8] fix: Redoc spelling --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5647e2fdc9..7205e4f7d6 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ examples. ## Live demo -If you want to see how ReDoc will render your OpenAPI definition, +If you want to see how Redoc will render your OpenAPI definition, you can try it out online at https://redocly.github.io/redoc/. A version of the Swagger Petstore API is displayed by default. @@ -138,7 +138,7 @@ to render your OpenAPI definition, refer to the See [**IE11 Support Notes**](docs/usage-with-ie11.md) for information on IE support for Redoc. -## ReDoc CLI +## Redoc CLI For more information on Redoc's commmand-line interface, refer to [**Using the Redoc CLI**](https://redoc.ly/docs/redoc/quickstart/cli/). From 669adddc9dc3590df997b234e274b849c708d715 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Wed, 22 Sep 2021 22:17:19 -0400 Subject: [PATCH 4/8] Updates per reviews and adds new logo --- README.md | 13 ++++++++----- docs/images/redoc.png | Bin 0 -> 8047 bytes 2 files changed, 8 insertions(+), 5 deletions(-) create mode 100644 docs/images/redoc.png diff --git a/README.md b/README.md index 5647e2fdc9..7f55d8af6e 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- ReDoc logo + ReDoc logo # Generate interactive API documentation from OpenAPI definitions @@ -13,10 +13,13 @@ ## About Redoc -Redoc is an open-source tool for generating OpenAPI(aka Swagger) definitions. By default -Redoc offers a three-panel, responsive layout: the left panel contains a search bar and navigation menu, -the central panel contains the documentation, and the right panel contains request and response -examples. +Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions. + +By default Redoc offers a three-panel, responsive layout: + +- The left panel contains a search bar and navigation menu. +- The central panel contains the documentation. +- The right panel contains request and response examples. ![ReDoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) diff --git a/docs/images/redoc.png b/docs/images/redoc.png new file mode 100644 index 0000000000000000000000000000000000000000..15579760928b664b526cc89aedceecfb72460154 GIT binary patch literal 8047 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 Date: Wed, 22 Sep 2021 22:20:49 -0400 Subject: [PATCH 5/8] Minor edits --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 93de728121..cc80f831f5 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ By default Redoc offers a three-panel, responsive layout: - The central panel contains the documentation. - The right panel contains request and response examples. -![ReDoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) +![Redoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) ## Live demo @@ -82,7 +82,7 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d - `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. ## Version Guidance -| ReDoc Release | OpenAPI Specification | +| 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 | From 1c8578ea8840b9e0cc8f66eda317c6839b9c1383 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 9 Oct 2021 14:40:39 -0400 Subject: [PATCH 6/8] Adds comparison table and OpenAPI link section --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index cc80f831f5..5074978bc0 100644 --- a/README.md +++ b/README.md @@ -32,23 +32,53 @@ 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. Redocly Reference docs - -Redoc Community Edition is free open-source software (OSS). -Redocly has developed extensive enhancements on top of Redoc Community Edition's open core, creating Redocly Reference Docs. -See [Comparison Redoc CE vs. Redocly Reference Docs](https://redoc.ly/redoc-vs-reference/) -for the main differences between the Redoc Community Edition and Redocly Reference Docs. - -## Deploy to GitHub -[Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) - -## Redoc as a service -[Redoc as a service](https://redoc.ly/workflows) +## Redoc vs. Reference vs. Portals + +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://redoc.ly/docs/developer-portal/introduction/) +- [Reference](https://redoc.ly/docs/api-reference-docs/getting-started/) +- [Redoc](https://redoc.ly/docs/redoc/quickstart/intro/) ## Features - Responsive three-panel design with menu/scrolling synchronization - [Multiple deployment options](https://redoc.ly/docs/redoc/quickstart/intro/) -- Deep linking support - [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/quickstart/cli/#redoc-cli-commands) - Ability to integrate your API introduction into the side menu - [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/quickstart/react/) @@ -99,6 +129,14 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d - [APIs.guru](https://apis.guru/api-doc/) - [BoxKnight](https://www.docs.boxknight.com/) +## Lint OpenAPI definitions + +Redocly's OpenAPI CLI is an open source command-line tool that you can use to lint +your OpenAPI definition. Linting helps you to catch errors and inconsistencies in your +OpenAPI definition before publishing. + +Refer to [Lint configuration](https://redoc.ly/docs/cli/guides/lint/) in the OpenAPI documentation for more information. + ## Deployment ### TL;DR final code example From 3cc6ea458973f7d8bb95e43687808c4743ebce39 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 9 Oct 2021 14:44:37 -0400 Subject: [PATCH 7/8] Minor edit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5074978bc0..82f09b27c6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- ReDoc logo + Redoc logo # Generate interactive API documentation from OpenAPI definitions From c4564de324d78c86e4436cf7ee0aa5b8c63f48ca Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 9 Oct 2021 14:46:36 -0400 Subject: [PATCH 8/8] Updates image src --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 82f09b27c6..3aad1e420b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- Redoc logo + Redoc logo # Generate interactive API documentation from OpenAPI definitions