Generate Swagger for your Rails project, with no code changes, in 2 / minutes
Tags: ruby, rails, vscode, productivity
Published: 2021-04-07 21:54:06

**Note: AppMap Swagger has been updated and incorporated into AppMap core. Learn more about how to generate OpenAPI (formerly Swagger) documentation in the [AppMap developer docs](http://appmap.io/docs/openapi)**

In this 2 1/2 minute video, I'm introducing a new tool for Ruby called [`appmap_swagger`](https://github.com/applandinc/appmap_swagger-ruby#appmap_swagger).

`appmap_swagger` eliminates the need to manually write [Swagger](https://swagger.io/specification/). It works by generating Swagger directly from your test cases. It doesn’t just look at your tests though; that’s not enough information to generate Swagger. It actually runs them. It sees every request, every mime type, every parameter, every header and every response. This information is generated by recording your test cases using a Ruby gem called [AppMap](https://marketplace.visualstudio.com/items?itemName=appland.appmap). 

Try using `appmap_swagger` as you work! As you write your code and run test cases, re-generate AppMaps by running the tests with `APPMAP=true`. Then run `bundle exec rake appmap:swagger`. To see how your web services are changing, run `bundle exec rake appmap:swagger:diff`. Here's an example from my own work, showing how routes are being changed, added, and removed:

```sh-session
$ bundle exec rake appmap:swagger:diff
changed       @ info.version
old value     : v0.22.0
new value     : v0.22.1
added         @ paths."/api/api_keys".delete.responses
added key     : 200
added value   : {"content"=>{"application/json"=>{}}}
removed       @ paths."/scenarios/{id}".put.requestBody.content."application/json".schema.properties.scenario.properties
removed key   : mapset
removed value : {"type"=>"string"}
removed       @ paths."/scenarios/{scenario_id}/save_as".post.requestBody.content."application/json".schema.properties.save_as.properties
removed key   : feature
removed value : {"type"=>"string"}
removed       @ paths."/scenarios/{scenario_id}/save_as".post.requestBody.content."application/json".schema.properties.save_as.properties
removed key   : feature_group
removed value : {"type"=>"string"}
```

Once I'm happy with what I see, and with the test coverage, I push the work-in-progress Swagger files up to my code repo. I create a Draft pull request as soon as I start coding, that way everyone can see what I’m doing, as I work. The generated Swagger file `openapi_stable.yaml` gives my colleagues a great view of any web services changes that I’m making. That makes the eventual code review of my pull request a lot easier, and it helps make sure that my changes to the web services API don’t break anyone else’s code.

Thanks for watching / reading! And if `appmap_swagger` interests you, be sure and check out the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap). It turns AppMaps into interactive, accurate software architecture diagrams right in your IDE. The dependency map, trace view, web services, SQL, and source code integration help you understand and optimize your code *before* code review. 

P.S. If you saw this post last week, my apologies for the re-publishing. It turned out that there were bugs in the Gem that kept it from working for a lot of people. So, I hope you'll give me another chance!