Update: 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.
Welcome back to my RailsConf 2021 presentation recap! Check out Part 1 and Part 2 in case you missed them. This post recaps the second demo I gave as part of my talk. Using rswag and appmap-swagger, I showed RailsConf attendees how to auto-generate Swagger files instead of manually writing them.
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 web services 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
How Swagger works
- Create HAML or JSON that describes the web services in detail
- Generate:
- Catalog of web services
- Interactive API testing from the catalog
- Client node snippets
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 rswag: Swagger 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.
- With appmap-swagger: Swagger 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 below. 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 sixth edition. Check it out here. Let us know what you think in Slack!
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.
Get AppMap