Microservices are commonly organized into multiple git repositories. This guide describes how to create a developer portal (using Redocly) with multiple microservices documented together.
Note: These are Redocly recommendations for documenting multiple microservices. You may choose to implement your microservices differently to this method.
Set up your microservice APIs so that each microservice API is responsible for its own API definition.
The OpenAPI definition would typically live within the same
git repository as the microservice itself.
Redocly's preferred option is connecting the microservices APIs to git repos for three reasons:
- Automated linting
- Automated bundling (into what we call snapshots)
- Automated links to previews of the microservices API reference (useful for normal change management process such as GitHub flow, Gitflow, or trunk-based development)
If Redocly's git app cannot be installed due to security reasons (connectivity is blocked due to firewalls, etc.), you will be unable to use this preferred option. Redocly has a CLI tool which can "push" APIs into our registry.
Redocly expects the developer portal source to be stored in a git repository. We recommend starting with the developer portal starter repo, which you can use as a template.
If you do not use GitHub, you can download the template and create a repository in your preferred git provider.
To set up the developer portal connection in Redocly Workflows, navigate to Portals > Add new.
Follow the steps to connect to your repository.
We recommend enabling previews from PRs (not for branches).
To add microservices APIs to the developer portal, reference the external OpenAPI definitions within the developer portal by using Redocly's API registry. For more information, see API Registry.
Redocly's API registry keeps a record of all usages, so when you update an API (in its production branch), the developer portal is updated automatically.
Once you have added your microservices API, complete these tasks to build your developer portal content:
- Find your snapshot URLs.
- Declare your API definitions.
- Add your
.page.yamlfile. For more information, see Adding pages manually.
- Define what to display in the left navigation.
- Customize your top navigation in the