RADAR is a static site generator for REST API documentation and is an implementation of the current version of the Open API specification (formerly known as Swagger). RADAR can be used by any Open API provider. Built on React/Redux, it offers searching, browsing and viewing REST documentation for any product and any version of that product. It is designed with large APIs in mind, where a single scrolling page of endpoints becomes too unwieldy.
The name RADAR is an acronym for Rest API Documentation Application in React.
Before you do anything:
This README assumes you are running a *nix machine.
- Running unit tests:
To start the application:
npm start- You'll need to run 2 servers for development, this command does the following:
npm run develop-webpack- Webpack dev server - this handles hot reloading the JS
npm run develop-express- Express dev server - this handles compiling the templates and baking in the test data
http://localhost:8080/docs/bitbucket/latest/<- This will load the
- You now have hot reloading of JS assets, and automatic rebundling. All without a reload. Cool, huh?
- You can now make changes to any JS or JSX files (or add more).
Note: changes to image assets are currently not auto-detected, so if you add or change any, you'll need to run
redux-devtools are installed. You can use
Ctrl+h to show/hide or
Ctrl+q to move them. They are useful for time-travel debugging and seeing what's going on in the app state.
We assume you will want to back RADAR with your own server.
server/dev-server.js file gives some insight into what a RADAR server will need to be able to do.
RADAR relies on wildcard routing to handle the file-fetching logic server-side, while keeping the routing for resources client-side.
This package only handles rendering a semi-static front end for displaying your documentation. How you store and/or version your docs is entirely up to you.
- JSON only; RADAR currently only supports JSON specs, YAML is not (yet) supported
- Referencing other files is not supported. The entire spec must be in one file.
Pull requests, issues and comments welcome. For pull requests:
- Add tests for new features and bug fixes
- Follow the existing style
- Separate unrelated changes into multiple pull requests
See the existing issues for things to start contributing.
For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.
Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).
Prior to merging your pull requests, please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual.
Copyright (c) 2016 Atlassian and others. Apache 2.0 licensed, see LICENSE.txt file.