📘 OpenAPI/Swagger-generated API Reference Documentation
Go to file
Lorna Jane Mitchell b3503f2109
Config docs and README refresh (#2393)
* docs: Give Redoc a landing page with overview and tldr instructions

* docs: move config to dedicated page

* docs: modernise README, link to resources

* docs: more detailed format for theme configurations

* fix: README formatting

* fix: Fix future tense errors and add exceptions for config fields as headings

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: minor updates from excellent pull request feedback

* docs: Remove the old quickstart, update HTML as the preferred onboarding method and improve docs/examples on that page

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

---------

Co-authored-by: Heather Cloward <heathercloward@gmail.com>
2023-09-21 15:19:27 +01:00
.github Config docs and README refresh (#2393) 2023-09-21 15:19:27 +01:00
.husky chore: run prettier & add husky pre-commit hook (#1800) 2021-11-24 16:11:45 +02:00
benchmark chore: migrate yarn -> npm 2020-03-17 11:06:03 +02:00
config fix: add node version to docker (#2005) 2022-05-12 16:52:16 +03:00
demo fix: more cases for react18 and cli integration (#2416) 2023-09-15 13:28:35 +03:00
docs Config docs and README refresh (#2393) 2023-09-21 15:19:27 +01:00
e2e chore: update cypress to 12.17.1 2023-07-27 13:09:38 +03:00
scripts feat: add clear cache for publish action (#2129) 2022-08-18 16:56:28 +03:00
src fix: more cases for react18 and cli integration (#2416) 2023-09-15 13:28:35 +03:00
tests/e2e feat: add callbacks support (#1224) 2020-04-08 14:04:58 +03:00
typings chore: upgrade deps 2020-07-25 20:15:14 +03:00
.dockerignore chore: migrate yarn -> npm 2020-03-17 11:06:03 +02:00
.editorconfig Initial React rewrite 2017-10-12 00:01:37 +03:00
.eslintrc.js fix: No maxLength label is displayed for arrays of items #1701 (#1765) 2022-01-05 17:11:05 +02:00
.gitignore chore: remove redoc-cli (#2320) 2023-05-18 17:53:26 +03:00
.npmignore fix: fix typings on npm 2018-05-31 15:41:57 +03:00
.prettierignore fix: exclusiveMin/Max shows incorect range (#1799) 2021-11-24 16:47:24 +02:00
.vale.ini docs: adds vale rules and workflow for running in CI (#2348) 2023-07-11 13:31:52 -04:00
CHANGELOG.md chore: v2.1.2 (#2413) 2023-09-11 13:31:28 +03:00
custom.d.ts chore: return genericObject for cli (#2178) 2022-10-04 15:50:57 +03:00
cypress.config.ts chore: update cypress to 12.17.1 2023-07-27 13:09:38 +03:00
karma.conf.js chore: try fix chrome headless on travis 2018-01-21 21:57:48 +02:00
LICENSE Update LICENSE 2018-05-08 10:23:45 -05:00
package-lock.json chore: v2.1.2 (#2413) 2023-09-11 13:31:28 +03:00
package.json chore: v2.1.2 (#2413) 2023-09-11 13:31:28 +03:00
README.md Config docs and README refresh (#2393) 2023-09-21 15:19:27 +01:00
tsconfig.json chore: remove redoc-cli (#2320) 2023-05-18 17:53:26 +03:00
tsconfig.lib.json fix: broken dropdowns with SSR by using forked react-dropdown-aria 2020-08-22 14:57:31 +03:00
tslint.json chore: fix tslint and tests 2020-03-16 19:15:40 +02:00
webpack.config.ts chore: update cypress to 12.17.1 2023-07-27 13:09:38 +03:00

Redoc logo

Generate interactive API documentation from OpenAPI definitions

npm License

bundle size npm

About Redoc

Redoc is an open source tool for generating documentation from OpenAPI (formerly 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

Live demo

If you want to see how Redoc renders 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 features

  • Responsive three-panel design with menu/scrolling synchronization
  • Support for OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0
  • Multiple deployment options
  • 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 specification extension
  • Simple integration with create-react-app
  • Code samples support (with vendor extension)

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 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 within the body tags:

    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>

Open the HTML file in your browser, and your API documentation is shown on the page.

Add your own spec-url to the <redoc> 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 for more details.

More usage options

Check out the deployment documentation 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 with additional features including:

  • Try-it console
  • Automated code samples
  • Pagination
  • Extra theme options

Documentation and resources

Showcase

A sample of the organizations using Redocly tools in the wild:

Pull requests to add your own API page to the list are welcome

Configuration

Redoc is highly configurable, see the configuration documentation for details.

OpenAPI specification extensions

Redoc uses the following specification extensions:

  • x-logo - is used to specify API logo
  • x-traitTag - useful for tags that refer to non-navigation properties like Pagination, Rate-Limits, etc
  • x-codeSamples - specify operation code samples
  • x-examples - specify JSON example for requests
  • x-nullable - mark schema param as a nullable
  • x-displayName - specify human-friendly names for the menu categories
  • x-tagGroups - group tags by categories in the side menu
  • x-servers - ability to specify different servers for API (backported from OpenAPI 3.0)
  • x-ignoredHeaderParameters - ability to specify header parameter names to ignore
  • x-additionalPropertiesName - ability to supply a descriptive name for the additional property keys
  • x-summary - for Response object, use as the response button text, with description rendered under the button
  • x-extendedDiscriminator - in Schemas, uses this to solve name-clash issues with the standard discriminator
  • 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 branch.

All the 2.x releases are deployed to npm and can be used with Redocly-cdn:

Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN (deprecated):

Development

see CONTRIBUTING.md