Seasony API
The Seasony project also required an API backend, made in tandem with the frontend. The development began at the project's final phases. Initially, we decided to create the documentation with a single JSON file. The result was a long and hard to follow file prone to errors.
After some Google search, we decided to use JSDoc. JSDoc creates the documentation much like CSS in JS. Each endpoint has all the documentation right above the code and uses the YAML format to render the Swagger interface result. Separating the documentation for each endpoint makes it easier to read, maintain, and debug.
Project
HYF Final project
Team of 15 developers
Seven weeks deadline
Full Stack App
Stack
Swagger
NodeJS
JSDoc
YAML
JavaScript
JSON
Repo
Site
Stack selection
Every Hack Your Future final project uses all the tech stack we learned through the seven-month intense Bootcamp and introduces new technologies such as KnexJS, Storybook, and Swagger. That means that we get to practice on the stack we've already learned, and we also get the opportunity to learn new tools. At the end of the project, we had a polished full-stack app.
Project challenges
Swagger is straightforward, and the Swagger Petstore example gives a solid understanding of how to use and document endpoints. It was challenging to switch between front and backend tasks, but the process of learning and see it coming together was very gratifying and rewarding.
Lessons learned
The primary lesson from working on this API was to learn how to create the documentation using JSDocs and YAML. It allows the documentation to be together with each endpoint, making it easier to maintain.