Browse the platform API

Open the platform API reference to browse the combined OpenAPI specification. The portal navigation also includes an API reference link. Search within Swagger to filter operations or expand an endpoint to inspect its inputs and responses. The Service selector starts at All services. Selecting an individual service loads only that service's spec, reducing the schema-resolution work Swagger does when expanding endpoints. The path count, spec fingerprint, and download link follow the selected service.

What the page includes

The page packages the repository's openapi.yaml↗ and the included services' individual specs with the vendored Swagger UI. The build changes the document title to Flow Platform API and preserves its paths and schemas. The service list is controlled by DEPLOYED_SERVICES in Makefile↗; it does not include every service in the repository or discover running services.

The header shows the portal's build revision and the source spec's SHA-256 fingerprint. This is a source snapshot, not an inventory of deployed versions. Services deploy independently, so their running APIs can differ from this snapshot. Locally, the spec includes working-tree changes even though the build revision identifies the checkout's latest commit.

Request execution (Try it out) is disabled. Enabling it requires mapping operations to their owning service URLs and configuring browser access and authentication for that environment.

Local use

Start the portal with ./localenv up docs-app, then open localhost:3501/api-docs. The APIs do not need to be running to browse the reference. The page uses bundled Swagger assets and does not fetch scripts or submit the spec to an external validator.

The dev and production build commands prepare the reference automatically. After regenerating the root spec during local development, run pnpm api-docs:generate from frontend/docs-app and refresh the page.

Deployment

The dev API reference is served by the docs app. Its Azure pipeline triggers on changes to frontend/docs-app, the root openapi.yaml, services/*/openapi.yaml, Makefile, or common/swaggerui/assets:

• Merging into develop builds and deploys the dev docs app.
• Merging into main builds and deploys the production docs app.

The pipeline stages the spec and Swagger assets in the app's Docker build context, builds and pushes the container, then upgrades its Helm release. A separate manual deployment is not defined by the pipeline. Pipeline enablement, permissions, and external approval policies are managed in Azure DevOps.

See frontend/docs-app/.azure/azure-pipelines.yml↗ and frontend/docs-app/.azure/build-deploy-nodeapp-template.yml↗ for the deployment.