Project starter: API Reference

Use Redoc to render API documentation for OpenAPI, AsyncAPI, or GraphQL descriptions. This starter project shows off some key features of a Redoc project, and gives you something you can use to begin.

The features include:

• OpenAPI and AsyncAPI documentation
• Versioned APIs
• Structured sidebar
• Brand styling with CSS

Get the project and set it up

Use the API reference docs starter project repository to begin. This project is a template repository, so click "Use this template" to get your own copy of the project.

Once you have your own copy of the project in a repository that you own, you can connect it to Reunite, Redocly's hosting platform, immediately.

To connect your repository in Reunite:

1. Log in to your Reunite account and Create a new project. The project is where you deploy your project from (note that only Redocly hosting is supported; these projects are not licensed to deploy from other platforms).

2. Connect the Git provider where your repository is hosted.

3. Wait for the project to build.

Tour the project features

This starter project has multiple features; we'll examine each one in turn.

API reference documentation

The project includes both OpenAPI and GraphQL APIs. Both APIs are accessible from the sidebar:

• Museum OpenAPI example description
• GraphQL example schema

The OpenAPI reference renders each operation, grouped by tag. All the request and response schema information is described in the central panel. On the right, request information, code samples and request examples are presented. Use the "Try it" button to see Replay, the interactive API explorer.

GraphQL reference documentation shows the queries and objects that the user can work with. In each section, the details are listed in the central panel, with copyable samples at the right hand side.

Add your own APIs to the project by putting the files in the apis/ directory, and adding a new group entry to the sidebar.

User feedback

Connect with users by being open to feedback. The default "sentiment" feedback is enabled, or you can configure the feedback settings

When you deploy your project with Reunite, the feedback is available from the project dashboard. Feedback entries can be archived once you've read or processed them.

Versioned APIs

Multiple versions of the Museum API are available, and we've added two versions to the project. When you are on the Museum API documentation, a version selector dropdown is shown so that you can pick which version of the reference you want to see.

To add multiple versions of an API:

• Add each version in directory with the version in the name, such as @v2/.
• Add a versions.yaml file alongside the version directories to control the display names and default values.

Check the documentation for working with versioned content for more information.

Custom styles

Making your API docs fit your brand and style was a key driver of our vision for Redoc. Dark mode is built in, switch your settings by clicking on the sun/moon in the top bar.

Edit the styles using CSS variables in @theme/styles.css to quickly replace the colors we picked for the starter project (you can inspect any element to find the CSS variable name used). Take it one step further by following the guide to style customization and making the project your own.

Powerful configuration

Many aspects of Redoc are configurable; so many that it's hard to know where to start! Check out the full list of configuration options and pick the elements that you would like to change.

Action points

Try these activities to get to know your Redoc project better:

• Edit @theme/styles.css to make the light theme sidebar a bit less... yellow.

• Add another API to the project, either your own, or perhaps one of the examples from https://apis.guru/. Include a link to the sidebar.

• Update redocly.yaml so that only your two favorite programming languages are represented in the OpenAPI code samples.