Welcome back to my RailsConf 2021 presentation recap! Check out Part 1 and Part 2 in case you missed them last week. This post recaps the second demo I gave as part of my talk. Using rswag and the
appmap_swagger gem, I showed RailsConf attendees how to auto-generate Swagger files instead of manually writing them.
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
The Swagger UI takes JSON or YAML files and generates an interactive catalog of your web services. The catalog contains routes, methods, status codes, parameters, request body, authentication methods and more. With Swagger, you can:
- See your whole web services catalog and actively interact with all of the API functions
- Debug your webservices in a very granular way
- Observe your web services test coverage visually
- Diff the web services changes by committing your Swagger YAML and comparing across versions using standard source diff
Writing Swagger files -- and keeping them accurate and up-to-date -- is a real challenge, so here are two ways of auto-generating these files:
With a gem called
rswagSwagger can be auto-generated from test cases. Rswag ensures a valid Swagger file thanks to assertion checks performed by rswag, and it’s very customizable.
appmap-swaggerSwagger can be auto-generated from AppMap files, which are recorded from test cases. appmap-swagger also ensures a valid Swagger file, but achieves more complete API coverage faster. You also don’t need to learn as much about the OpenAPI format to use appmap-swagger.
You can watch this portion of my RailsConf talk in the video clip above. If you want to follow along in the code or look it up later, I’ve created a branch called
swagger within the Land of Apps fork of the Rails Sample App. Check it out, and let us know what you think in the AppMap Discord!
Coming up next... In the fourth and final installment of this blog series, I’m going to recap the remaining demo of my RailsConf talk: how to auto-document database schemas.