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

Ivan Goncharov 5cfc0b4479 Fix internal links inside docs.		2016-07-17 19:02:27 +03:00
build	Cleanup unused code	2016-07-17 18:16:09 +03:00
demo	Uncomment 'star-me' on demo-page 🌟	2016-06-29 22:43:45 +03:00
docs	Fix internal links inside docs.	2016-07-17 19:02:27 +03:00
lib	Implement Copy/Expand/Collapse buttons	2016-07-17 18:07:51 +03:00
tests	fix tests	2016-07-01 18:33:42 +03:00
typings	Replace marked with remarkable	2016-06-22 12:42:24 +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
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	v0.16.0	2016-07-17 18:12:05 +03:00
protractor.conf.js	Fix sauce maxDuration values	2016-07-17 18:24:01 +03:00
README.md	Add info about CDN to README	2016-06-30 11:34:39 +03:00
system.config.js	Update openapi-sampler: new formats and additionalProperties support (fixes #66 )	2016-07-15 22:35:06 +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

Swagger-generated API Reference Documentation

Live demo

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 uses font options from the parent element
    So override default browser styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
        font-family: Verdana, Geneva, sans-serif;
        font-size: 14px;
        color: #333;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'>
    </redoc>
    <script src="bower_components/redoc/dist/redoc.min.js"> </script>
  </body>
</html>

1. Install redoc

Install using bower:

bower install redoc

or using npm:

npm install redoc --save

Alternatively, you can reference redoc directly from CDN:

latest release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js
particular release, e.g. v0.14.0: https://rebilly.github.io/ReDoc/releases/v0.14.0/redoc.min.js

2. Reference redoc script in HTML

Then reference redoc.min.js in your HTML page:

<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

Options

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

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 options names as the keys. For example:

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

Running locally

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