Nov 12, 2016
Staggered by Swagger I
or: common language, uncommon interpretation
Swagger is getting to be a big thing of late. On my project, I have the opportunity to continue to bring form to a Big Ball of Mud. In four years we have been able to separate the HTML page generation from the back-end PHP Morass of Code™, so that now the PHP generates JSON that is passed to handlebars templates on a Node.js server.
That JSON comes from raw SQL queries mostly, and the data from those queries was poked and prodded into HTML interspersed in the PHP code. The data therefore is none too organized — there is no model per se, just a menagerie of data structures. In tackling this problem, slap an ORM or other persistence layer on top of the relational database, but in our case the relational database is poorly normalized and schema-less — there are no PK-FK constraints, for instance, so a generated schema diagram would show boxes of wholly independent tables.
One could take the middle-out approach: design an object data model, then write client code against an interface to that, and have the initial implementation grab the gobbledygook data structures returned from the calls to the back-end, then force those into the new data model. That done, you could then start normalizing the database and replace the messy initial implementation with a simpler and cleaner persistence layer.
I chose instead a top-down approach: model a RESTful API based on what is presented on our website. The result is a list of resources (identified by URIs) along with JSON in the request/response bodies. The JSON becomes our “model”, although I prefer the term “representation” because the schema of the data transferred between client and server will vary depending on operation and context, but a model schema remains constant.
Apigee, the folks behind the core Swagger toolset, have proposed and submitted a vocabulary to the Open API Initiative organization, called the Open API Specification (OAS). By defining a REST API in YAML or JSON using the OAS vocabulary, you theoretically have a huge number of tools available to you that can read the specification an generate servers, clients, documentation, tests and what-have-you. In practice, there are (as you might expect) a few wrinkles in moving from one tool to another using the same OAS-based API specification.
In the next installment, I’ll go through three or four AOS editing tools and demonstrate that you don’t always wind up with the same specification you started with.
