Generate an OpenAPI Spec from your AppMaps

In this video
Learn how to generate an OpenAPI specification (formerly known as a Swagger specification) for your application. Keep your OpenAPI documentation up-to-date automatically by running the option to generate OpenAPI definitions. Commit, publish, or import your OpenAPI specification into Postman to interact and test your application.

Links mentioned
Rails Sample Application
OpenAPI Specification
Postman API Platform

Follow along

Welcome to AppMap, in this tutorial we are going to generate an openapi specification for our API endpoints in this sample ruby on rails application.

The OpenAPI specification, which is formerly known as Swagger Specification, is a community driven open standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to the source code.

To generate your Open API spec, we’ll need to make sure we have either test case coverage over your API endpoints to generate AppMaps with OR remote recordings of those same API endpoints being interacted with.

In this example, we already have AppMap installed in our project. If you don’t have AppMap installed in your project yet, refer to our previous tutorial videos for adding AppMap to your project.

In this project, I have complete test cases for my API endpoints, so i’ll run a recording of my tests to generate these AppMaps.

You’ll see as I run my tests with AppMap enabled, all my AppMaps are being generated real time. At this point I can stop and explore my AppMaps, or I can review any findings from the AppMap Analysis tool.

Continuing on to the OpenAPI generation page, you can see that AppMap has identified 92 unique HTTP routes in my app.

Without AppMap, engineers need to manually update the OpenAPI spec and keep updated over time as new functionality is created in your app. But with AppMap, we can simply click on the OpenAPI generation button, and we’ll build this file for you based on the AppMaps from this specific branch of code and display it for you within VSCode.

From here I can save this file locally, commit it to my project, or I can import this as a collection into the popular tool, Postman to further interact with my application’s APIs.

---