mirror of
https://github.com/Redocly/redoc.git
synced 2025-08-08 06:04:56 +03:00
Update README.md
This commit is contained in:
parent
8e5a5e8a83
commit
549c8a3c1f
146
README.md
146
README.md
|
@ -1,69 +1,85 @@
|
||||||
<div align="center">
|
<div align="center">
|
||||||
<img alt="ReDoc logo" src="https://raw.githubusercontent.com/Redocly/redoc/master/docs/images/redoc-logo.png" width="400px" />
|
<img alt="ReDoc logo" src="https://raw.githubusercontent.com/Redocly/redoc/master/docs/images/redoc-logo.png" width="400px" /style="margin-bottom: 15px">
|
||||||
|
|
||||||
**OpenAPI/Swagger-generated API Reference Documentation**
|
<hr style="margin-bottom: 25px">
|
||||||
|
|
||||||
[](https://travis-ci.org/Redocly/redoc) [](https://coveralls.io/github/Redocly/redoc?branch=master) [](https://david-dm.org/Redocly/redoc) [](https://david-dm.org/Redocly/redoc#info=devDependencies) [](https://www.npmjs.com/package/redoc) [](https://github.com/Redocly/redoc/blob/master/LICENSE)
|
<!-- **OpenAPI/Swagger-generated API Reference Documentation** -->
|
||||||
|
|
||||||
|
**ReDoc transforms your OpenAPI definition into comprehensive and interactive documentation, fast.**
|
||||||
|
|
||||||
|
[](https://travis-ci.org/Redocly/redoc) [](https://coveralls.io/github/Redocly/redoc?branch=master) [](https://david-dm.org/Redocly/redoc) [](https://david-dm.org/Redocly/redoc#info=devDependencies) [](https://www.npmjs.com/package/redoc) [](https://github.com/Redocly/redoc/blob/master/LICENSE) [](https://www.npmjs.com/package/redoc) [](https://www.jsdelivr.com/package/npm/redoc) [](https://hub.docker.com/r/redocly/redoc/)
|
||||||
|
|
||||||
|
<!-- [](https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js) -->
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
The current ReDoc version is `2.0`. For older version please see the [`v1.x`](https://github.com/Redocly/redoc/tree/v1.x) branch.
|
||||||
|
|
||||||
[](https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js) [](https://www.npmjs.com/package/redoc) [](https://www.jsdelivr.com/package/npm/redoc) [](https://hub.docker.com/r/redocly/redoc/)
|
|
||||||
|
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
**This is README for `2.0` version of ReDoc (React based). README for `1.x` version is on the branch [v1.x](https://github.com/Redocly/redoc/tree/v1.x)**
|
|
||||||
|
## What's In This Document
|
||||||
|
|
||||||
|
- [Demo](#demo)
|
||||||
|
- [Features](#features)
|
||||||
|
- [Premium Features](#premium-features)
|
||||||
|
- [Live Examples](#live-examples)
|
||||||
|
- [Roadmap](#roadmap)
|
||||||
|
- [Getting Started](#getting-started)
|
||||||
|
- [Deployment](#deployment)
|
||||||
|
- [Releases](#releases)
|
||||||
|
- [Version Guidance](#version-guidance)
|
||||||
|
- [Development](#development)
|
||||||
|
|
||||||
|
|
||||||

|
## Demo
|
||||||
|
|
||||||
## [Live demo](http://redocly.github.io/redoc/)
|
[<img alt="ReDoc live demo" src="https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png">](http://redocly.github.io/redoc/)
|
||||||
|
|
||||||
[<img alt="Deploy to Github" src="http://i.imgur.com/YZmaqk3.png" height="60px">](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) [<img alt="ReDoc as a service" src="http://i.imgur.com/edqdCv6.png" height="60px">](https://redoc.ly) [<img alt="Customization services" src="http://i.imgur.com/c4sUF7M.png" height="60px">](https://redoc.ly/#services)
|
|
||||||
|
|
||||||
|
<!-- [<img alt="Deploy to Github" src="http://i.imgur.com/YZmaqk3.png" height="60px">](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) [<img alt="ReDoc as a service" src="http://i.imgur.com/edqdCv6.png" height="60px">](https://redoc.ly) [<img alt="Customization services" src="http://i.imgur.com/c4sUF7M.png" height="60px">](https://redoc.ly/#services) -->
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
- Extremely easy deployment
|
|
||||||
- [redoc-cli](https://github.com/Redocly/redoc/blob/master/cli/README.md) with ability to bundle your docs into **zero-dependency** HTML file
|
All of these features are available in our open source community edition.
|
||||||
- Server Side Rendering ready
|
|
||||||
- The widest OpenAPI v2.0 features support (yes, it supports even `discriminator`) <br>
|
- Deploy **extremely fast** via CDN, npm, CLI, or Docker.
|
||||||
|
- Bundle your docs into a **zero-dependency** HTML file (when using [`redoc-cli`]()).
|
||||||
|
- Integrate with any React app, with client or server-side rendering.
|
||||||
|
- Take full advantage of OpenAPI 2.0/3.0 features, from `discriminator` to `allOf`.
|
||||||
|
<br> <br>
|
||||||

|

|
||||||
- OpenAPI 3.0 support
|
- Use **interactive** documentation for nested objects
|
||||||
- Neat **interactive** documentation for nested objects <br>
|
<br> <br>
|
||||||

|

|
||||||
- Code samples support (via vendor extension) <br>
|
<br> <br>
|
||||||
|
- Include **code samples** (via vendor extension)
|
||||||
|
<br> <br>
|
||||||

|

|
||||||
- Responsive three-panel design with menu/scrolling synchronization
|
<br> <br>
|
||||||
- Integrate API Introduction into side menu - ReDoc takes advantage of markdown headings from OpenAPI description field. It pulls them into side menu and also supports deep linking.
|
- Get a fully responsive, three-panel design out of the box (with menu/scrolling synchronization)
|
||||||
- High-level grouping in side-menu via [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) vendor extension
|
- Integrate your API Introduction into the side menu (with support for deep linking)
|
||||||
- Simple integration with `create-react-app` ([sample](https://github.com/APIs-guru/create-react-app-redoc))
|
- Create high-level groupings in the side menu with the [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) vendor extension
|
||||||
- Branding/customizations via [`theme` option](#redoc-options-object)
|
- Match your docs and your brand by using the [`theme` option](#redoc-options-object)
|
||||||
|
|
||||||
## Roadmap
|
## Premium Features
|
||||||
- [x] ~~[OpenAPI v3.0 support](https://github.com/Redocly/redoc/issues/312)~~
|
|
||||||
- [x] ~~performance optimizations~~
|
|
||||||
- [x] ~~better navigation (menu improvements + search)~~
|
|
||||||
- [x] ~~React rewrite~~
|
|
||||||
- [x] ~~docs pre-rendering (performance and SEO)~~
|
|
||||||
- [ ] ability to simple branding/styling
|
|
||||||
- [ ] built-in API Console
|
|
||||||
|
|
||||||
## Releases
|
These features are availale in our hosted or on-premise premium edition.
|
||||||
**Important:** all the 2.x releases are deployed to npm and can be used via jsdeliver:
|
|
||||||
- particular release, e.g. `v2.0.0-alpha.15`: https://cdn.jsdelivr.net/npm/redoc@2.0.0-alpha.17/bundles/redoc.standalone.js
|
|
||||||
- `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)**:
|
- SEO Friendly URLs
|
||||||
- particular release, e.g. `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js
|
- 10x Page Load Speed
|
||||||
- `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js
|
- 'Try It' API console
|
||||||
- `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.
|
- Multiple Servers
|
||||||
|
- OAS3 security schemes
|
||||||
|
- Enhanced Search
|
||||||
|
- Additional Theming Control
|
||||||
|
- Embedded Markdown
|
||||||
|
|
||||||
## Version Guidance
|
## Live Examples
|
||||||
| ReDoc Release | OpenAPI Specification |
|
|
||||||
|:--------------|:----------------------|
|
|
||||||
| 2.0.0-alpha.x | 3.0, 2.0 |
|
|
||||||
| 1.19.x | 2.0 |
|
|
||||||
| 1.18.x | 2.0 |
|
|
||||||
| 1.17.x | 2.0 |
|
|
||||||
|
|
||||||
## Some Real-life usages
|
|
||||||
- [Rebilly](https://rebilly-api.redoc.ly/)
|
- [Rebilly](https://rebilly-api.redoc.ly/)
|
||||||
- [Docker Engine](https://docs.docker.com/engine/api/v1.25/)
|
- [Docker Engine](https://docs.docker.com/engine/api/v1.25/)
|
||||||
- [Zuora](https://www.zuora.com/developer/api-reference/)
|
- [Zuora](https://www.zuora.com/developer/api-reference/)
|
||||||
|
@ -71,6 +87,24 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d
|
||||||
- [Commbox](https://www.commbox.io/api/)
|
- [Commbox](https://www.commbox.io/api/)
|
||||||
- [APIs.guru](https://apis.guru/api-doc/)
|
- [APIs.guru](https://apis.guru/api-doc/)
|
||||||
- [FastAPI](https://github.com/tiangolo/fastapi)
|
- [FastAPI](https://github.com/tiangolo/fastapi)
|
||||||
|
- [Spoke Phone](https://developer.spokephone.com/)
|
||||||
|
- [SignRequest](https://signrequest.com/api/v1/docs/)
|
||||||
|
|
||||||
|
## Roadmap
|
||||||
|
- [x] ~~OpenAPI v3.0 support~~
|
||||||
|
- [x] ~~performance optimizations~~
|
||||||
|
- [x] ~~better navigation (menu improvements + search)~~
|
||||||
|
- [x] ~~React rewrite~~
|
||||||
|
- [x] ~~docs pre-rendering (performance and SEO)~~
|
||||||
|
- [ ] use `redoc-cli` under the hood
|
||||||
|
- [ ] address accessibility issues
|
||||||
|
- [ ] add support for links (OpenAPI v3)
|
||||||
|
- [ ] add `x-webhooks` support
|
||||||
|
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
Do you need to create, contribute to, or split an OpenAPI definition? We created [`create-openapi-repo`](https://github.com/Redocly/create-openapi-repo) just for you.
|
||||||
|
|
||||||
## Deployment
|
## Deployment
|
||||||
|
|
||||||
|
@ -200,7 +234,7 @@ Also you may rewrite some predefined environment variables defined in [Dockerfil
|
||||||
|
|
||||||
## ReDoc CLI
|
## ReDoc CLI
|
||||||
|
|
||||||
[See here](https://github.com/Redocly/redoc/blob/master/cli/README.md)
|
[`redoc-cli`](https://github.com/Redocly/redoc/tree/master/cli) allows you to run a local server that renders your spec with ReDoc, and to bundle ReDoc and your spec into a **zero-dependency** HTML file.
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
|
@ -270,6 +304,24 @@ Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
|
||||||
}, document.getElementById('redoc-container'))
|
}, document.getElementById('redoc-container'))
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Releases
|
||||||
|
**Important:** all the 2.x releases are deployed to npm and can be used via jsdeliver:
|
||||||
|
- particular release, e.g. `v2.0.0-alpha.15`: https://cdn.jsdelivr.net/npm/redoc@2.0.0-alpha.17/bundles/redoc.standalone.js
|
||||||
|
- `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
|
||||||
|
- `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.
|
||||||
|
|
||||||
|
## Version Guidance
|
||||||
|
| ReDoc Release | OpenAPI Specification |
|
||||||
|
|:--------------|:----------------------|
|
||||||
|
| 2.0.0-alpha.x | 3.0, 2.0 |
|
||||||
|
| 1.19.x | 2.0 |
|
||||||
|
| 1.18.x | 2.0 |
|
||||||
|
| 1.17.x | 2.0 |
|
||||||
|
|
||||||
-----------
|
-----------
|
||||||
## Development
|
## Development
|
||||||
see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
|
Want to help us build ReDoc? Awesome! Please read our [Contributing Guide](.github/CONTRIBUTING.md) first.
|
||||||
|
|
Loading…
Reference in New Issue
Block a user