Foxglove now leverages OpenAPI to generate routes and documentation for our REST API.

Though Foxglove primarily focuses on building tools to accelerate robotics development, we also like to think about ways to streamline our own workflows. Integrating OpenAPI helps us ship software more efficiently and deliver consistent value to our users.

Experiencing developer friction

Foxglove provides a set of REST APIs to help robotics teams organize and access their data. We initially wrote our APIs with Typescript to minimize context-switching between the front-end and back-end. Each route lived as a separate file in our codebase, with the logic for its supported HTTP verbs. Routes used common modules for authentication, but typically implemented their own unique validation rules.

While this approach was easy to bootstrap, we ran into several points of friction as our team grew and the API evolved. Development slowed significantly as we added more server routes – each new route required an engineer to hand-author Typescript types and corresponding JSON schemas to feed into our validation library (AJV).

It was also increasingly difficult to keep our documentation updated and accurate. Since routes were implemented and then documented separately – often by different engineers – many nuances about route behavior and user impact were lost in translation. It was also painful to validate that a route’s behavior aligned with its documentation, since each route was responsible for its own authentication and response types.

We had to find a way to reduce boilerplate server code and automatically generate accurate documentation that could evolve with our routes.

Integrating with OpenAPI

To solve these problems, we decided to generate server code from a hand-authored spec file. To avoid reinventing parsers and validators, we decided to use a standard format like OpenAPI, we hoped to avoid reinventing parsers and validators.

Our generator uses @apidevtools/swagger-parser to read a YAML file, validates that it conforms to the OpenAPI spec, and resolves references. It then converts each path’s query and body parameters into TypeScript types using json-schema-to-typescript, and finally generates that route’s source code as a string output:

process diagram

As a final step, our generator formats the generated code with prettier for easier reading.

Using our generated output

To more easily leverage our generated types and schemas (index.generated.ts), we stored those files alongside their corresponding business logic files (index.ts) and unit tests (index.test.ts).

Our generated files each provide a controller function that accepts one argument – the HTTP verbs that need to be implemented for that route. We import this function from our hand-authored business logic, thus effectively checking types and validating both requests and responses:



Realizing the benefits of OpenAPI

With OpenAPI, we’ve reduced the amount of boilerplate code we write, kept our automatically deployed documentation up-to-date with minimal effort, and even set up linting to enforce consistent formatting in our spec files.

We’ve also leveraged the OpenAPI spec’s security feature. Our API keys have role-based access controls to limit their access. Once we specify the role required under each path’s HTTP verb, the generator verifies that the authorization is applied before invoking the hand-authored business logic. This offloads route security, so that engineers can now write business logic and review changes without worrying about this overhead.

We’re excited to continue leaning on spec files for generating client libraries in different languages. By streamlining our own development workflows, we’ve been able to deliver higher quality software and more features faster for our users.


Foxglove Studio users can now annotate their camera images with the TextAnnotation message schema – whether you’re using ROS, Protobuf, or any other supported serialization format.

Text annotations can dramatically enrich how you debug your robots’ perception modules. By rendering useful metadata in-context, text annotations can facilitate faster comprehension and richer analysis.

bounding boxes

Labeling bounding boxes can help roboticists quickly understand how their perception stack is performing.

To display your own annotated images in Foxglove Studio, check out our text-annotation-demo in the MCAP GitHub repo. This simple example renders a ball bouncing around a scene over time, and publishes two TextAnnotation messages to label the scene with the timestamp (top left corner of the scene) and the ball’s position (above our perceived bouncing box).

Run the demo script to output a text-annotation-example.mcap file for visualization in Foxglove Studio. Add an Image panel to your layout, and toggle on the “annotations” topic in the panel settings to display both labels:

panel settings

While this exercise demonstrates a rather simple use case for annotated images, we hope it inspires your team to annotate your images – with perception labels, error messages, or other useful metadata.

For more information on image annotations, you can check out our docs or contact us directly in our Slack community with any questions.


Foxglove Studio’s redesigned navigation makes it easier than ever for you to use Studio’s information-rich interface and explore your robotics data.

We’ve reorganized screen space to make it easy to zero in on the information that matters most to you. The new top navigation bar summarizes data source information and highlights quick actions like adding a panel, opening a data source, or choosing a layout.

Most noticeably, we’ve split the original sidebar menu into two panes – one on either side of the layout–  for more efficient analysis. Whether you want to view your data source's topics, set variables, or configure panel settings, you can use these collapsible sidebars to inspect different aspects of your workspace simultaneously.

top nav breakdown

We hope these changes make your development workflow even more intuitive. To share feedback or ask questions, feel free to contact us directly or join our Slack community for support.


Introducing Foxglove Studio's New Navigation

Read more:

Ready to try Foxglove?