Senior Swagger: Part 2, Fillify Your Data
The first post was a little misleading. I wrote and published that 5 weeks into my senior project. At time of publish, I was already done with the first functional addition, request parameter data population, a concept we will from now on refer to as “fillifying.”
To reiterate the basic problem, an API call can contain any number of parameters, information needed to process the request. These parameters can be contained in the path, the query string and/or the body of the request, leaving a multitude of cases for me to cover in my tool. The project prior to starting development merely placed the parameters in their indicated positions and assigned an ‘obvious indicator’ as the value. This then required the developer, post-generation, to manually edit all of the request parameters. This makes for poor tool ergonomics.
With the problem fresh in your mind, let’s fillify.
When adding anything to the functionality of this project, one has to get their hands dirty with the templates that structure the generated code. These templates, read and compiled by the Handlebars.js module, have their own syntax for indicating where code will be dynamically inserted. This syntax comes with a few helpers to iterate over the provided data or use conditional logic, but it also enables the developer to create their own custom helper functions. This is exactly how I tackled fillifying.
Like I mentioned earlier, there are a few different spots data can be placed in a request, the path, query string and body. The approach was to implement fillify for each of these individually, completing one, merging it into master, then starting the next. Luckily, a Github user had identified the need for this functionality in the path parameters, and implemented it himself, a pull request which I merged and garnered inspiration for the name ‘fillify.’ This feature became known as ‘pathify.’ One down.
I then opened the issues on the repo for query string and body parameters and began working on the former. The first challenge was deciding how specific I would let the developer get with providing values for parameters in their API.
I would have to parse the API and the corresponding data object passed in to determine where the values belonged, so I wanted to reduce the complexity while still offering enough utility. I decided on implementing a path-by-path specification for query string parameters, shown here in the example. The body parameters were specified as path-by-operation, a little more detailed. With the usage nailed down, I could start implementing the Handlebars helper to parse the data object.
The custom helpers in Handlebars are so extremely useful, turning a pretty useful module into an extremely powerful code-generation engine. The helpers for fillify all followed a similar form, searching for the current path and parameters being parsed in the data object passed by the developer. If the path parameter isn’t specified, the obvious indicator is returned, allowing for some post-generation customization.
Bodify was quite similar to querify, but with another level of specification in the data object, allowing the developer to define values for parameters unique to a path’s operation.
With pathify, querify and bodify finished, I move on to the more challenging piece of functionality, sequence test generation. I will start by mocking up what the generated code should look like, identifying necessary modules to handle the asynchronous nature of HTTP requests within a synchronous test.
Tests will be written in advance, followed by basic implementation for a single use-case for validation of the idea and I will end by defining more complicated, customized use-cases.
Let’s get it!
If you would like to contribute to the main project, please find the repo on Github. ❤