# appmap-swagger

`appmap-swagger` generates [Swagger 3](https://swagger.io/specification/) (aka OpenAPI) YAML from [AppMap](https://appland.org/) 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](https://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

```sh-session
$ 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`

```sh-session
$ 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"]
```