OpenAPI / Swagger

The gateway self-describes its REST API using the OpenAPI 3.1.0 specification. Every level of the URL hierarchy exposes a /docs endpoint that returns a context-scoped OpenAPI spec - so tools and developers always have an accurate, up-to-date description of available operations.

Accessing the Spec

Append /docs to any valid API path:

# Full gateway spec (all endpoints)
curl http://localhost:8080/api/v1/docs | jq .

# Spec scoped to the components collection
curl http://localhost:8080/api/v1/components/docs

# Spec for a specific component and its resource collections
curl http://localhost:8080/api/v1/components/my_sensor/docs

# Spec for one resource collection (e.g. data)
curl http://localhost:8080/api/v1/components/my_sensor/data/docs

Entity-level specs reflect the actual capabilities of each entity at runtime. Plugin-registered vendor routes also appear when the requested path matches a plugin route prefix.

Swagger UI

For an interactive API browser, build the gateway with Swagger UI support:

colcon build --cmake-args -DENABLE_SWAGGER_UI=ON

Then open http://localhost:8080/api/v1/swagger-ui in your browser. The UI assets are embedded in the binary - no CDN dependency at runtime.

Note

The CMake configure step downloads assets from unpkg.com, so network access is required during the build.

Using with External Tools

The spec returned by /docs is standard OpenAPI and works with any compatible tooling:

Postman - Import http://localhost:8080/api/v1/docs as a URL to auto-generate a request collection.
Client generators - Feed the spec to openapi-generator to produce typed clients in Python, TypeScript, Go, and many other languages.
Documentation - Render with Redoc or any OpenAPI-compatible doc renderer.

Configuration

The /docs endpoints are enabled by default. To disable them:

ros2_medkit_gateway:
  ros__parameters:
    docs:
      enabled: false

When disabled, all /docs endpoints return HTTP 501.

See Server Configuration for the full parameter reference.