{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"document-microservices-apis-with-the-developer-portal","__idx":0},"children":["Document microservices APIs with the developer portal"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Microservices are commonly organized into multiple git repositories. This guide describes how to create a developer portal (using Redocly) with multiple microservices documented together."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," These are Redocly recommendations for documenting multiple microservices. You may choose to implement your microservices differently to this method."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-organize-your-microservices-api-definitions","__idx":1},"children":["Step 1: Organize your microservices API definitions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up your microservice APIs so that each microservice API is responsible for its own API definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The OpenAPI definition would typically live within the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["git"]}," repository as the microservice itself."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-connect-each-microservices-api-to-redoclys-api-registry","__idx":2},"children":["Step 2: Connect each microservices API to Redocly's API registry"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly's preferred option is connecting the microservices APIs to git repos for three reasons:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automated linting"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automated bundling (into what we call snapshots)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automated links to previews of the microservices API reference (useful for normal change management process such as GitHub flow, Gitflow, or trunk-based development)"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If Redocly's git app cannot be installed due to security reasons (connectivity is blocked due to firewalls, etc.), you are unable to use this preferred option. Redocly has a CLI tool which can ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/commands/push"},"children":["\"push\" APIs"]}," into our registry."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-set-up-a-developer-portal-repo-that-redocly-can-access","__idx":3},"children":["Step 3: Set up a developer portal repo (that Redocly can access)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly expects the developer portal source to be stored in a git repository. We recommend starting with the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/developer-portal-starter"},"children":["developer portal starter repo"]},", which you can use as a template."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you do not use GitHub, you can download the template and create a repository in your preferred git provider."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-connect-the-repo-to-redocly","__idx":4},"children":["Step 4: Connect the repo to Redocly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To set up the developer portal connection in Redocly Workflows, navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Portals > Add new"]},"."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/add-new-dev-portal-6b8fde553c69cc40.png","alt":"Add a new developer portal"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the steps to connect to your repository."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Tip"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend enabling previews from PRs (not for branches)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-add-microservices-apis-to-your-developer-portal","__idx":5},"children":["Step 5: Add microservices APIs to your developer portal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-registry/overview"},"children":["API Registry"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have added your microservices API, complete these tasks to build your developer portal content:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Find your ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-registry/guides/snapshots"},"children":["snapshot URLs"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Declare your ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/reference-docs-integration-advanced#step-1-declare-your-api-definitions"},"children":["API definitions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file. For more information, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/reference-docs-integration-advanced#step-2-add-pages-that-reference-the-definitions"},"children":["Adding pages manually"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define what to display in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/configuration/sidebar-nav"},"children":["left navigation"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/navbars-footers"},"children":["Customize your top navigation"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"diagram-microservices-api-with-developer-portal","__idx":6},"children":["Diagram: Microservices API with developer portal"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n subgraph Customer Product\n ms1[Microservice 1]\n ms2[Microservice 2]\n ms3[Microservice 3]\n api1[API definition 1]\n api2[API definition 2]\n api3[API definition 3]\n ms1 -- includes --> api1\n ms2 -- includes --> api2\n ms3 -- includes --> api3\n end\n apir[Redocly API registry]\n ref[API reference docs]\n api1 -- connected to --> apir\n api2 -- connected to --> apir\n api3 -- connected to --> apir\n dp[API developer portal]\n apir -- rendered within --> ref\n ref -- integrated with --> dp\n","diagramHtml":"","diagramHtmlDark":""},"children":[]}]},"frontmatter":{"seo":{"title":"How to document microservices APIs with the developer portal"},"excludeFromSearch":true},"tagList":["admonition","partial"],"title":"How to document microservices APIs with the developer portal","lastModified":"2025-05-28T16:01:32.000Z"}