Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2024-11-22 08:36:33 +03:00
Code Issues Packages Projects Releases Wiki Activity
📘 OpenAPI/Swagger-generated API Reference Documentation
679 Commits 13 Branches 225 Tags 86 MiB
TypeScript 98.1%
JavaScript 0.8%
Shell 0.4%
HTML 0.4%
Dockerfile 0.3%
40a3102934
Go to file
Roman Hotsiy 40a3102934
Fix dropdown on demo
2016-08-21 10:49:53 +03:00
build Fix tests failure on PR 2016-08-01 07:22:49 +03:00
demo Fix dropdown on demo 2016-08-21 10:49:53 +03:00
docs Improve headings for vendor extensions 2016-07-17 21:48:56 +03:00
lib Fix markdown newlines to be gfm (fixes #82) 2016-08-21 10:17:41 +03:00
tests Validate that api scheme is used correctly 2016-08-01 10:26:10 +10:00
typings If API supports both HTTP and HTTPS use HTTPS (fixes #72) 2016-07-26 14:51:59 +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 try releases to github pages 2016-04-30 22:55:29 +03:00
.npmignore prepare for npm publish 2016-01-12 23:36:23 +02:00
.travis.yml include basic e2e to the tescases needed for deployment 2016-05-10 11:02:47 +03:00
bower.json Add additional keywords 2016-02-24 18:25:49 +02:00
CHANGELOG.md Add changelog 2016-08-13 02:33:06 +03:00
gulpfile.js Add gulp copydebug task 2016-05-20 20:51:31 +03:00
karma.conf.js update to the latest angular 2016-07-01 15:53:16 +03:00
LICENSE Update LICENSE 2015-10-30 07:56:43 -05:00
package.json Add special representation for enum with one value (fixes #70) 2016-08-12 20:42:41 +03:00
protractor.conf.js Fix sauce maxDuration values 2016-07-17 18:24:01 +03:00
README.md Update README.md 2016-08-04 19:14:50 +03:00
system.config.js If API supports both HTTP and HTTPS use HTTPS (fixes #72) 2016-07-26 14:51:59 +03:00
tsconfig.json Fix coverage 2016-06-16 15:44:14 +03:00
tslint.json Fix lint erorrs, fix typescript version 2016-06-15 21:48:04 +03:00
typings.json Migrate tests to TypeScript 2016-06-12 20:44:34 +03:00

README.md

ReDoc

OpenAPI/Swagger-generated API Reference Documentation

Build Status Coverage Status Tested on APIs.guru Code Climate David Stories in Ready

npm Bower License

Browser Compatibility

ReDoc demo

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:

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

<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
})

Running locally

  1. Clone repository git clone https://github.com/Rebilly/ReDoc.git
  2. Go to the project folder cd ReDoc
  3. Install node modules and front-end dependencies npm install npm run jspm-install
  4. (optional) Replace demo/swagger.json with your own schema
  5. Start the server npm start
  6. Open http://localhost:9000