mirror of https://github.com/Redocly/redoc.git synced 2024-11-10 19:06:34 +03:00

📘 OpenAPI/Swagger-generated API Reference Documentation

api-documentation documentation-generator documentation-tool hacktoberfest openapi openapi3 openapi31 openapi-specification reactjs redoc starred-redocly-repo starred-repo swagger

Go to file

Roman Hotsiy 5583c8a313 Enabled a few codelyzer rules		2016-10-23 20:36:34 +03:00
build	rename external jquery for module build	2016-10-18 17:46:41 +03:00
demo	Just a little typo	2016-09-07 14:41:10 -07:00
docs	Add x-nullable to the docs	2016-08-31 22:45:34 +03:00
lib	Enabled a few codelyzer rules	2016-10-23 20:36:34 +03:00
manual-types	Fix npm start on windows, fixes #119 , #118	2016-09-28 00:30:33 +03:00
tests	Refactor + minor fixes/optimizations	2016-10-23 20:18:42 +03:00
.codeclimate.yml	fix codeclimate config	2015-12-26 19:47:35 +02:00
.eslintignore	Updated eslint	2015-12-12 22:10:59 +02:00
.gitignore	Move to webpack + AoT compilation ✨	2016-08-28 21:46:10 +03:00
.npmignore	prepare for npm publish	2016-01-12 23:36:23 +02:00
.travis.yml	build module before npm publish	2016-10-14 12:19:53 +03:00
bower.json	Add additional keywords	2016-02-24 18:25:49 +02:00
CHANGELOG.md	Update CHANGELOG	2016-10-14 13:20:17 +03:00
karma.conf.js	Ignore changes (watcher) during tests	2016-08-29 12:05:44 +03:00
LICENSE	Update LICENSE	2015-10-30 07:56:43 -05:00
package.json	v1.4.1	2016-10-18 17:06:28 +03:00
protractor.conf.js	fix IE detection in protractor	2016-08-29 01:05:34 +03:00
README.md	fix issue #116	2016-09-22 09:13:29 +02:00
tsconfig.json	try fix build again	2016-10-18 17:34:18 +03:00
tslint.json	Enabled a few codelyzer rules	2016-10-23 20:36:34 +03:00

README.md

ReDoc

OpenAPI/Swagger-generated API Reference Documentation

Live demo

Features

Extremely easy deployment
It’s free and open-source project under MIT license
The widest OpenAPI features support (yes, it supports even discriminator)
Neat documentation for nested objects
Code samples support (via vendor extension)
Responsive three-panel design with menu/scrolling synchronization
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.

Roadmap

docs pre-rendering (performance and SEO)
ability to simple customization
built-in API Console

Releases

We host latest and all the previous ReDoc releases on GitHub Pages-based CDN:

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 [not for production]

Deployment

TL;DR

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <!-- needed for adaptive design -->
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
    <script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"> </script>
  </body>
</html>

That's all folks!

1. Install ReDoc (skip this step for CDN)

Install using bower:

bower install redoc

or using npm:

npm install redoc --save

2. Reference redoc script in HTML

For CDN:

<script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"> </script>

For bower:

<script src="bower_components/redoc/dist/redoc.min.js"> </script>

For npm:

<script src="node_modules/redoc/dist/redoc.min.js"> </script>

3. Add `<redoc>` element to your page

<redoc spec-url="url/to/your/spec"></redoc>

4. Enjoy 😄

Configuration

Swagger vendor extensions

ReDoc makes use of the following vendor extensions:

x-logo - is used to specify API logo
x-traitTag - useful for handling out common things like Pagination, Rate-Limits, etc
x-code-samples - specify operation code samples
x-nullable - mark schema param as a nullable

`<redoc>` tag attributes

spec-url - relative or absolute url to your spec file;
scroll-y-offset - 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; scroll-y-offset 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 will be used as offset;
- function: A getter function. Must return a number representing the offset (in pixels);
suppress-warnings - if set, warnings are not rendered at the top of documentation (they still are logged to the console).

Advanced usage

Instead of adding spec-url attribute to the <redoc> element you can initialize ReDoc via globally exposed Redoc object:

Redoc.init(specUrl, options)

options is javascript object with camel-cased version of <redoc> tag attribute names as the keys, e.g.:

Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
  scrollYOffset: 50
})

Development

Running local dev-server

Clone repository git clone https://github.com/Rebilly/ReDoc.git
Go to the project folder cd ReDoc
Install dependencies npm install
(Temporary step, will be obsolete after fixing #97) Compile CSS

npm run build:sass

(optional) Replace demo/swagger.yaml with your own schema
Start the server npm start
Open http://localhost:9000

README.md Unescape Escape