This is where my project started.
I had never really written a Swagger spec before this and despite being in the industry for a bit, I only rarely interacted with a live Swagger server. I was very excited to start this part of the project because this was effectively how I started architecting the system. It really started with me heading over to editor.swagger.io (a suggestion that the project description had given), getting a base swagger spec that was completed then understanding and editing what was there. It took me a few hours to get comfortable with it, poking and prodding at the example spec and trying to make it into what I wanted. I highly recommend it for those new to writing Swagger specs. Just getting the instant feedback of whether what I wrote was great and it really helped me properly articulate my thoughts with the tool.
Despite that, my first spec wasn’t the best but it helped get the architecture ‘on paper’.
The major architectural design I made was splitting the actions into multiple endpoints. I had felt that I wanted to keep each action separate from each other and so each controller could focus on the validation it needed to do as opposed having to figure out which manipulation was being done and then doing the proper validation on the manipulation’s input. In practice, this led to a bit of repeat code though it didn’t affect how quickly I was able to complete a new endpoint as each endpoints structure was the same. I also decided that the type of images I would support were only png and jpeg images as I was sure that any technology I chose to do the image manipulations would be able to work with these formats.
Going back to the swagger documentation, what I also tried to do was think about potential error messages that the endpoint could have and started articulating them. This was done because one of the project’s technical requirements was the proper use of HTTP codes to articulate particular server responses. I really wanted to make sure I had that done and I was thinking about that initially so that I wouldn’t forget to include them when I started writing code. This document was effectively my design document initially so there was a fair amount of time when I started coding, I ended up pulling this up and referring to it.
An interesting part of the initial swagger spec was the use of ‘not implemented’ in the spec. Something that I had thought but when I initially wrote the spec was articulating that certain HTTP verbs were not in use and I wanted to explicitly say that in my swagger spec. Every endpoint had a bunch of entries for ‘not implemented’ for the 5 other basic HTTP verbs that weren’t being used.
This of course made it into my code and my API will return a 501 if an endpoint and verb isn’t implemented. I would later find out that it wasn’t necessary to articulate that an HTTP verb was not implemented. Whatever the swagger spec didn’t have was assumed to not be implemented. All my implementations did was to clutter up the documentation. Once the swagger documentation was completed, I would quickly spin up a quick Node TypeScript project based on previous work I had done with Node in the MVC pattern. Defining some quick routes and some empty controllers and away I would go.
Something I found myself really interested in doing as I worked on the project was being able to show the swagger documentation online. This honestly came from working and seeing other Engineers display their swagger documentation online. I had very little practical experience with Swagger directly and so seeing this at work really inspired me to do the same with my work. The way I accomplished this was the use of this npm package. This would spin up an auto-generated HTML page that would show my swagger spec and give the user the ability to make API calls using CURL. The setup wasn’t completely trivial as I had two issues I had to sort out. First, my swagger spec was done in a YAML file which is what you would typically get if you exported your spec from editor.swagger.io (which I had). Node doesn’t natively read YAML so I had to get another package to allow Node to read the YAML file to be consumed by the npm package. Secondly, by default, all the tabs for each endpoint were open and would crowd the web page. While it wasn’t a deal breaker, it was annoying and so I spent a bit of time trying to find the right configuration to have them all start close. It’s not difficult at all but I wanted to note that putting the configuration in the right place took longer than I wish to admit.
Here’s a link to the swagger documentation: https://github.com/chadstewart/you-go-backend-project/blob/main/nodejs/api-docs/api-spec.yaml
In the next article of this series, I talk about using TypeScript and how it made the project a joy to work on!
Top comments (2)
I've been working for the first time in manually writing a swagger spec for a NextJS project, (in the past it was automatically generated) and I'm quite enjoying the experience with swagger-jsdoc. Having the ability to split your definitions and having them right up your controllers is great! If you have the chance check it out.
I saw that and I think honestly, I think I would use it next time. I didn't use it for this project because I had invested so much time into writing the yaml file (which I somehow managed not to get any indentation errors the entire time I was working on it, lol) that I didn't want to just throw it away to do even more writing on the spec.
In the future though, I definitely like the idea of defining the spec right in the controller as opposed to as a separate file. You see the definition every time you go into that controller which is helpful for building it out and it makes changing it feel significantly less intimidating. I plan on doing a v2 of the API so I might use swagger-jsdoc for the new endpoints, but I dunno, lol.