@appland/appmap-swagger

Generate Swagger (OpenAPI) documentation from AppMaps

Usage no npm install needed!

<script type="module">
  import applandAppmapSwagger from 'https://cdn.skypack.dev/@appland/appmap-swagger';
</script>

README

appmap-swagger

appmap-swagger generates Swagger 3 (aka OpenAPI) YAML from AppMap data.

AppMaps contain rich information about HTTP server requests. appmap-swagger collects and organizes this information into the Swagger format.

The more (and better) functional and integration tests you write, the more Swagger you get. And better yet, it's always accurate because it reflects the actual behavior of your code.

Once you've generated Swagger, you can configure your web app to serve the Swagger API and UI. Then you can interact directly with your API, in the context of your app, through the Swagger UI. It's a powerful way to browse, understand, and debug your API.

Supported languages

appmap-swagger works with any language that has an AppMap client. Consult appland.org for a current list of clients, plus usage instructions and examples.

How it works

  1. Install the AppMap client for your programming language.
  2. Record AppMaps by running test cases.
  3. Run appmap-swagger to generate Swagger paths and components. Swagger YAML is printed to stdout.
  4. Merge the paths and components into a wrapper template using some custom code in your project, or a standardized wrapper such as the appmap:swagger Rake task.
  5. Open your Swagger docs using the Swagger API or Swagger UI.

Example

To try out appmap-swagger:

  1. Clone this repo
  2. npm install to get dependencies.
  3. node ./cli.js generate --directory test/fixtures/appland

Usage

List commands

$ appmap-swagger --help     
appmap-swagger <command>

Commands:
  appmap-swagger generate  Generate Swagger from AppMaps in a directory

Options:
      --version  Show version number                         [boolean]
  -v, --verbose  Run with verbose logging                    [boolean]
      --help     Show help

appmap-swagger generate

$ appmap-swagger generate --help
appmap-swagger generate

Generate Swagger from AppMaps in a directory

Options:
      --version    Show version number                       [boolean]
  -v, --verbose    Run with verbose logging                  [boolean]
      --help       Show help                                 [boolean]
      --directory  directory to recursively inspect for AppMaps
                                               [default: "tmp/appmap"]