This quickstart is for users who want to try the Redocly API registry in less than 5 minutes.
In this quickstart, you will learn how to add your first API to the registry, validate it, and preview API docs.
If you prefer watching a video, here's the link to ourAPI registry tutorial.
To learn more about how the API registry works, start from theOverview page.
Make sure you fulfill the following prerequisites for working with the API registry:
Create an account in Redocly Workflows. You can register for an accountdirectly on the Workflows page or by using the invitation link from an existing Workflows user. Depending on the registration method you chose, you will either create a new organization or join an existing one. Your account in the organization must have the permission to add APIs to the registry.
Create an account with a version control service provider such as GitHub or GitLab. We recommend GitHub, and we use it in the examples throughout this guide.
You may need to install and configure the Redocly app for your version control service if it has not been done by the Workflows organization owner. Check oursource control documentation for instructions.
In this step, you will use our template GitHub repository to set up an API definition project.
Log into GitHub and access the Redoclyopenapi-starter repository.
On the repository page, selectUse this template. This opens the dialog to create a new repository from the template.
In theCreate a new repository from... dialog, select your account as theOwner and set a custom name for your repository underRepository name. Choose whether you want the repository to be public or private. Leave theInclude all branches checkbox unselected.
- SelectCreate repository from template to complete the action and exit the dialog.
You should now be able to access your newly created repository. An example API definition calledopenapi.yaml is in theopenapi folder.
In this step, you will connect your new repository to the API registry and add the example API definition.
Log intoRedocly Workflows and access the API registry page.
On the API registry page, selectAdd API.
- The dialog for adding a new API definition opens. In theChoose source step, chooseGitHub (recommended) and selectNext.
- In theSource settings step underGitHub organizations, select the GitHub organization associated with your GitHub account. The Redocly app must be installed and configured for this organization.
UnderRepositories, select the repository you have created from our template.
UnderSource settings, select the
mainbranch. Provide the path to the API definition root file (in our case, it's theopenapi/openapi.yamlfile) and selectNext.
- In theName step, set a custom name and version for the API, and selectFinish to close the dialog.
Your API definition should now be added to the API registry. You will be redirected to the API versionOverview page, where the first build will automatically start. The build process validates and bundles your API definition, produces a snapshot, and generates API documentation.
In this step, you will check the validation status of your API definition in the API registry, and start a new build.
On theOverview page of your API version, find theLogs section. It should contain a single record of your first build. Select this record to view details about the build.
On the log details page, look for validation status messages. If the API definition is valid, there will be no errors or warnings in the build output. You can view the output by selectingShow terminal (3). When the terminal is active, selectShow issues to display errors and warnings if there are any.
SelectOpenAPI (1) to access some handy options, like downloading your API definition snapshot as a JSON or YAML file, and copying the direct link to the snapshot.
- To start a new build and validate the API definition again, selectRestart (2).
You have successfully added an API definition to the API registry and validated it.
In this step, you will preview the automatically generated API documentation for your API.
On theOverview page of your API version, find thePrimary branch section. It should contain theAPI docs button. Select this button to access the API docs for your API version.
You may be prompted to log in, so use the same credentials you used to log into Redocly Workflows. Your API documentation will open in a new browser tab.
You have successfully created an API with corresponding documentation in the API registry. The link to your API documentation will always be available on the API versionOverview page.