Generate Swagger for your Rails project, with no code changes, in 2 / minutes

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

In this 2 1/2 minute video, I'm introducing a new tool for Ruby called appmap_swagger.

appmap_swagger eliminates the need to manually write Swagger. 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.

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:

$ 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. 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!

Comments

[kadru]

Great work, I will check it

[Maartz]

Ho boy, that's pretty neat. Got some Rails apps at work with lots of tests but not so much documentation on exposed interfaces.
Thanks !