mirror of https://github.com/Redocly/redoc.git synced 2024-11-14 12:56:34 +03:00

Lorna Jane Mitchell 4fd22f6d74

docs: Add docs tooling to align with publishing to main site (#2484 )

* docs: add markdownlint and some link checks alongside vale

* docs: add link checker config and fix/update some links reported broken

* docs: update markdownlint action

* docs: fix markdown table formatting

* docs: Unpin Vale version and pick up the latest

2024-01-29 16:39:44 +00:00

3.8 KiB

Raw Blame History

seo

title
Redoc deployment guide

Redoc deployment guide

Redoc offers multiple options for rendering your OpenAPI definition. You should select the option that best fits your needs.

The following options are supported:

Live demo: The live demo offers a fast way to see how your OpenAPI renders with Redoc. A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your definition and select TRY IT.
HTML element: Using the HTML element works well for typical website deployments.
React component: Using the React component is an option for users with a React-based application.
Docker image: Using the Docker image works in a container-based deployment.
Redocly CLI: Using the Redocly CLI is an option for users who prefer to use a command-line interface.

Before you start

OpenAPI definition

You need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions:

OpenAPI 3.0
- Museum Example API
- Petstore Sample OpenAPI Definition
OpenAPI 2.0
- Thingful OpenAPI Definition
- Fitbit Plus OpenAPI Definition

{% admonition type="info" name="OpenAPI specification" %} For more information on the OpenAPI specification, refer to the Learning OpenAPI 3 section in the documentation. {% /admonition %}

How to run Redoc locally

If you want to view your Redoc output locally, you can simulate an HTTP server.

Redocly CLI

Redocly CLI is an open source command-line tool that includes a command for simulating an HTTP server to provide a preview of your OpenAPI definition locally.

If you have Redocly CLI installed, cd into your project directory and run the following command:

redocly preview-docs openapi.yaml

Replace openapi.yaml in the example command with the file path to your OpenAPI definition.

By default, without providing a port, the preview starts on port 8080, and can be accessed at http://localhost:8080. To exit the preview, use control+C.

You can alter the port if you are using 8080 already, for example:

redocly preview-docs -p 8888 openapi.yaml

Replace openapi.yaml in the example command with the file path to your OpenAPI definition.

For more information about the preview-docs command, refer to Redocly CLI commands in the Redocly CLI documentation.

Python

If you have Python 3 installed, cd into your project directory and run the following command:

python3 -m http.server

If you have Python 2 installed, cd into your project directory and run the following command:

python -m SimpleHTTPServer 8000

The output after entering the command provides the local URL where the preview can be accessed. To exit the preview, use control-C.

Node.js

If you have Node.js installed, install http-server using the following npm command:

npm install -g http-server

Then, cd into your project directory and run the following command:

http - server;