OpenAPI Generation with CI

The AppMap CLI provides an openapi subcommand to automatically generate an OpenAPI v3 compatible spec file from your AppMaps. Those AppMaps can be generated by your CI system via your existing test case suite. Due to this requirement, ensure your openapi command runs after your test cases have completed and AppMaps have been generated.

This guide describes how to use the openapi command in a basic, non-parallelized build job.

In your CI build job, you’ll want to make sure you have AppMap configured with your project. Refer to the test case recording documentation to learn how to add AppMap to record your test cases.

  1. Run the test cases to generate AppMaps
  2. Use the openapi command to export the API definitions

Run the test cases to generate AppMaps

Modify your build step that runs your application’s test cases to generate AppMaps. The specifics of this depend on your language and framework. See the recording test cases reference for details.

Use the openapi command to export the API definitions

Add in a step to run the AppMap CLI openapi command within your continuous integration(CI) build command. The simplest way to run the AppMap CLI is by using the Node npx command. Ensure that your Github Action has a supported version of Node.js to run this command. Refer to the Node.js requirements for install for the supported Node.js versions.

With a supported node.js version in your build project - add a line to generate the OpenAPI definition.

Note This needs to happen in the step AFTER your tests finish in your build task because it needs the AppMaps generated and available within the build.


$ bundle exec rake test
Started with run options --seed 30389

  36/36: [====================================] 100% Time: 00:00:02, Time: 00:00:02

Finished in 2.97104s
36 tests, 282 assertions, 0 failures, 0 errors, 0 skips

$ npx @appland/appmap@latest openapi --output-file openapi.yml

After generating your OpenAPI docs you can integrate AppMap OpenAPI with a 3rd party service

Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!