Rocket Doc is a React app that generates documentation from an OpenAPI 3.1 files.
The goal of this project is to provide a simple and easy-to-use tool, with minimal dependencies, to allow for a maintainable and customizable documentation generation.
Here is an example of the UI with Swagger Petstore example
You can use Rocket Doc as a React component in your application. First, install the package using yarn or npm:
yarn add @rocket-doc/app openapi3-ts tailwindcss
# or
npm install @rocket-doc/app openapi3-ts tailwindcssThen, import and use the RocketDoc component in your React application:
import React from 'react';
import ReactDOM from 'react-dom';
import { RocketDoc } from '@rocket-doc/app';
ReactDOM.render(
<RocketDoc
specUrl="https://api.example.com/openapi.json"
config={{
defaultExpandedDepth: 2,
routerType: "hash"
}}
/>,
document.getElementById('root')
);You can also use Rocket Doc directly in the browser by including the necessary scripts and adding a <rocket-doc /> DOM element:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/png" href="/rocket-doc.png" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Rocket Doc</title>
<script crossorigin src="https://unpkg.com/react@18/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
<script crossorigin src="https://unpkg.com/@rocket-doc/app@1.0.1/dist/index.umd.js"></script>
</head>
<body>
<rocket-doc
spec-url="https://api.example.com/openapi.json"
config='{"defaultExpandedDepth": 2, "routerType": "hash"}'
/>
</body>
</html>You can configure the Rocket Doc component using the following options, either as props in the React component or as attributes in the DOM element. All options are optional. Object attributes (in the DOM element) should be passed as JSON strings.
| Prop name | Attribute Name | Type | Description |
|---|---|---|---|
config |
config |
AppConfig |
The application configuration object. This can include various settings to customize the behavior and appearance of the documentation. |
logo |
logo |
string |
The URL of the logo image to be displayed in the navigation bar. |
specUrl |
specUrl |
string |
The URL of the OpenAPI specification file to be loaded. |
specRequiredSecurity |
spec-required-security |
OpenAPI SecurityScheme |
The security scheme required to access the OpenAPI specification. It matches the OpenAPI specification for a security scheme. |
specRequiredSecurityScopes |
spec-required-security-scopes |
string[] |
The scopes required for the security scheme. |
showFileImport |
show-file-import |
boolean |
A boolean flag to show or hide the file import option in the UI. |
extensions |
extensions |
Extensions |
An object containing extensions to customize the behavior of the documentation. |
The AppConfig object allows you to customize various settings for the Rocket Doc application. Below are the available options:
| Option Name | Type | Default | Description |
|---|---|---|---|
defaultExpandedDepth |
number |
2 |
The default depth to which the documentation tree should be expanded. |
routerType |
'hash' | 'browser' |
'hash' |
The type of router to use for navigation. |
basePath |
string |
'' |
The base path for the application. Useful if the app is served from a subdirectory. |
defaultTitle |
string |
'Rocket Doc' |
The default title for the documentation pages. Before it is loaded from the OpenAPI file |
The Extensions object allows you to customize the rendering of the Rocket Doc application. An extension is a function that takes arguments and returns a component to render. Below are the available options:
| Property | Type | Description |
|---|---|---|
| fieldDetails | (req: { name: string; schema: SchemaObject; fullSpec: OpenAPIObject }) => { component: (null | React.ComponentType); disablePadding?: boolean; } |
This function is called for every field in a schema. It takes the name of the field, the OAPI schema and the OAPI fullSpec. It must return a react component ( null for no row to be rendered), and an optional boolean to disable left aligment padding. |
The goal of this project is to have minimal dependencies. The following are the dependencies used in this project:
- PrismJS
- Code Editor # Edition overlay for PrismJS
- Fast XML Parser
- YAML
- React Markdown
- OpenAPI 3.1 support
- Schema display
- Operations filtering
- Try it out feature
- Code generation for requests
- Syntax highlighting for requests and responses
- Support for loading OpenAPI files from URL
- Support to retain application credentials
- Support for authenticated routes to get OpenAPI files
- Support for OpenAPI extensions
- Support for webhooks
- Support for OAuth 2.0
- Customizable theme
Feel free to submit issues or pull requests for any improvements or bug fixes.
To install the necessary dependencies, run:
yarnTo start the development server, run:
yarn devThis will start the application and you can view it in your browser.
This project is licensed under the MIT License.