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!
Top comments (2)
Great work, I will check it
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 !