The OpenAPI Specification, formerly known as Swagger Specification, is a community-driven open standard and programming language-agnostic interface description for HTTP APIs. It allows humans and computers to discover and understand the capabilities of a service without requiring access to the source code.
[ Become a Red Hat Certified Architect and boost your career. ]
AppMap is an open source tool used by tens of thousands of developers to visualize their application's runtime behavior. Unlike static analyzers, AppMap records the details of how an application runs and uses that information to find design flaws, security holes, and performance issues.
Because AppMap records how an application executes at runtime, it can see and record all of the API calls processed, including the schema of each request and response. Using the AppMap command-line interface (CLI) (or the VS Code or JetBrains extension), a developer can automatically output OpenAPI Specifications for an app.
While it's often recommended to create your OpenAPI docs first and then build out the corresponding API endpoints from the spec, modern software development is usually messier. Developers are frequently tossed into old projects with limited documentation. Creating these docs by hand is error-prone and annoying to keep current as the code changes.
The easiest way to get started with AppMap is by installing the VS Code or JetBrains extension, which walks users through the entire process. But if you are not already using one of those code editors or just love to live on the command line, you can install the AppMap client locally.
Since this is a Ruby project, add one line to the top of the Gemfile to include AppMap recording in development and testing:
gem 'appmap', :groups => [:development, :test]
bundle install to download and install AppMap into your project.
It's important to add the AppMap gem before any other gems, so it can observe the other gems in the application.
[ Learn how to build a flexible foundation for your organization. Download An architect's guide to multicloud infrastructure. ]
You can also run the
@appland/appmap project installer command via
npx, which lets you easily execute Node package binaries. The installer will identify the language of your project and set up the libraries for you if you don't want to do it manually.
$ npx @appland/appmap install -d /Users/dev_user/repos/sample_app_6th_ed ? Multiple project types were found in /Users/dev_user/repos/sample_app_6th_ed. Select one to continue. (Use arrow keys) ❯ Bundler yarn
bundler to automate adding the gem to your Gemfile and validate its setup.
? Multiple project types were found in /Users/dev_user/repos/sample_app_6th_ed. Select one to continue. Bundler Installing AppMap agent for .... ? AppMap is about to be installed. Confirm the details below. Project type: Bundler Project directory: /Users/dev_user/repos/sample_app_6th_ed Git remote: origin email@example.com:land-of-apps/sample_app_6th_ed.git (fetch) Ruby version: 3.0.2p107 Gem home: /Users/dev_user/.asdf/installs/ruby/3.0.2/lib/ruby/gems/3.0.0 Is this correct? Yes ✔ Installing AppMap... ✔ Validating the AppMap agent...
Now with AppMap installed, you need to record the application. There are a few ways to do that so that AppMap can see all of the API requests used to populate the OpenAPI specification file.
1. Record a test case
AppMap integrates with many popular testing frameworks, so you can run your tests to interact with all your API endpoints. This sample Ruby application has extensive test coverage, so you can simply run tests, and AppMap will generate one AppMap per test.
$ bundle exec rails test AppMap minitest recording is enabled because RAILS_ENV is 'test' Running via Spring preloader in process 42539 Started with run options --seed 58694 67/67: [=========================================================================================================================================================] 100% Time: 00:00:04, Time: 00:00:04 Finished in 4.21250s 67 tests, 282 assertions, 0 failures, 0 errors, 0 skips
2. Use remote recording
A remote recording is a great way to record your application if you don't have robust test case coverage or want to record a sequence of HTTP requests or other user interactions.
You can remotely record your application by running it locally, in a Docker container, or in a development environment. Since AppMap records everything in a request, including parameters and variables, it is not recommended to record production applications as you may inadvertently record sensitive data.
The first step in recording remotely is to run your application. In my example, I'll run the
rails server command:
$ bundle exec rails server => Booting Puma => Rails 220.127.116.11 application starting in development => Run `rails server --help` for more startup options AppMap remote recording is enabled because RAILS_ENV is 'development' AppMap requests recording is enabled because RAILS_ENV is 'development' Puma starting in single mode... * Puma version: 5.3.2 (ruby 3.0.2-p107) ("Sweetnighter") * Min threads: 5 * Max threads: 5 * Environment: development * PID: 48707 * Listening on http://127.0.0.1:3000 * Listening on http://[::1]:3000 Use Ctrl-C to stop
The output indicates that remote recording is enabled. Next, run the
record command on the command line to start the recording process:
$ npx @appland/appmap record remote ✔ Checking if the AppMap agent is available at http://localhost:3000/ ╭─────────────────────────────────────────────────────────╮ │ │ │ AppMap agent is available at http://localhost:3000/ │ │ │ ╰─────────────────────────────────────────────────────────╯ ? Press enter to start recording
When you are ready to start recording, press Enter, and then interact with your application by clicking around a web UI or issuing API calls to various endpoints. Try to keep recordings focused on a specific interaction to keep the AppMap from getting unnecessarily large.
Complete the recording by pressing Enter again, and your AppMap will open in your browser (or within VS Code or JetBrains if you use those editor extensions):
? Press enter to stop recording ╭────────────────────────────────────────────────────────╮ │ │ │ Recording has finished, with 908856 bytes of data. │ │ │ ╰────────────────────────────────────────────────────────╯ ? Choose a name for your AppMap: User Login ✔ Saving recording to User Login.appmap.json in directory tmp/appmap/remote ╭──────────────────╮ │ │ │ AppMap saved │ │ │ ╰──────────────────╯ Opening tmp/appmap/remote/User Login.appmap.json ? What would you like to do next: (Use arrow keys) ❯ Reopen tmp/appmap/remote/User Login.appmap.json Exit
[ Download Event-driven architecture for a hybrid cloud blueprint. ]
3. Request recording
Another way to generate AppMaps is by recording each individual request. This is currently supported for Ruby on Rails applications, with support planned for Python Django applications.
For this method, run your application, and AppMap request recording will be enabled by default and interact with your application. AppMap will generate a single AppMap per request and open each:
$ ls -lt tmp/appmap/requests/ | head total 6800 drwxr-xr-x 19 dev_user staff 608 Oct 5 14:22 1664994122_863181_http_localhost_3000_users_1 -rw-r--r-- 1 dev_user staff 478242 Oct 5 14:22 1664994122_863181_http_localhost_3000_users_1.appmap.json drwxr-xr-x 19 dev_user staff 608 Oct 5 14:22 1664994122_821723_http_localhost_3000_microposts_295 -rw-r--r-- 1 dev_user staff 125491 Oct 5 14:22 1664994122_821723_http_localhost_3000_microposts_295.appmap.json drwxr-xr-x 19 dev_user staff 608 Oct 5 14:22 1664994120_190062_http_localhost_3000_users_1 -rw-r--r-- 1 dev_user staff 473555 Oct 5 14:22 1664994120_190062_http_localhost_3000_users_1.appmap.json drwxr-xr-x 19 dev_user staff 608 Oct 5 14:21 1664994118_6177652_http_localhost_3000_users -rw-r--r-- 1 dev_user staff 316685 Oct 5 14:21 1664994118_6177652_http_localhost_3000_users.appmap.json
Generate an OpenAPI spec
Once you have AppMaps of your API requests, you can run a single command to output the OpenAPI v3-supported specification file. Use the results with other tools, including Hoppscotch, an open source API development ecosystem, or Postman, another popular commercially available API tool:
npx @appland/appmap openapi --output-file openapi.yml
You can now import this file into Hoppscotch as a new collection by navigating to the Collections button on the right-hand side.
Select the Import/Export icon.
Choose Import from OpenAPI.
Finally, select the OpenAPI file you created in the previous step.
You can use these tools to interact more easily with your APIs, test new or updated features, and export the OpenAPI Specifications to your users, so they know how to interact with your application.