RapiDoc Documentation

RapiDoc is a lightweight and fast Custom Element designed for viewing OpenAPI specifications. It supports Swagger 2.0 and OpenAPI 3.x.x and is designed to work with any web framework (React, Vue, Angular, Lit) or even with no framework at all.

Key capabilities include:

• Making live API calls directly from the UI.
• Extensive branding and personalization (themes, typography, colors).
• High usability features like expanded models/examples by default and side-by-side request/response views.
• Customization via standard CSS and JavaScript attribute manipulation.

To build the project and generate the standalone distribution file, follow these steps:

1. Clone or download the repository.
2. Install dependencies using npm install.
3. Run the build command to generate rapidoc-min.js. This is the only file required for production use.

npm install
npm run build

For local development, you can start a web server to view your changes. Use the serve command, which will start a server at http://localhost:8080.

npm run serve

You can pass custom RapiDoc configuration options (like themes or server URLs) to the Docker container using the RAPIDOC_OPTIONS environment variable. This variable accepts a string of space-separated key-value pairs formatted as key='value'.

# Example 1: Enable dark mode
docker run -it --rm -p 80:80 \
  -e SPEC_URL="http://petstore.swagger.io/v2/swagger.json" \
  -e RAPIDOC_OPTIONS="theme='dark'" mrin9/rapidoc

# Example 2: Enable dark mode and provide a custom API server URL
docker run -it --rm -p 80:80 \
  -e SPEC_URL="http://petstore.swagger.io/v2/swagger.json" \
  -e RAPIDOC_OPTIONS="theme='dark' server-url='http://localhost:8080/api'" mrin9/rapidoc

To view a specification stored on your local disk, mount the file into the Nginx server directory inside the container using a volume (-v) and set SPEC_URL to the filename within the container's web root (/usr/share/nginx/html/).

# Mount the local spec onto nginx server (available in the docker container)
docker run -it --rm -p 80:80 \
  -v $(pwd)/my-openapi.yaml:/usr/share/nginx/html/my-openapi.yaml \
  -e SPEC_URL="my-openapi.yaml" mrin9/rapidoc

To view an OpenAPI specification hosted on a web server, run the RapiDoc Docker image and provide the SPEC_URL environment variable pointing to your JSON or YAML file.

docker run -it --rm -p 80:80 -e SPEC_URL="http://petstore.swagger.io/v2/swagger.json" rapidoc

Once you have generated rapidoc-min.js, you can include it in your HTML file using a <script> tag. Because RapiDoc is a Custom Element, you can then use the <rapi-doc> tag (or similar, as defined by the element) within your HTML to render the specification.

<script type="text/javascript" src="rapidoc-min.js"></script>
</body>

To view the OpenAPI specification (defined in openapi.yaml) locally in your browser, use the serve command via npm. This will start a local web server.

npm run serve