API Documentation 📚

This is a sub package of this microservice that holds the API docs. the API docs is a package that is published to npm (check the package json). The reason it is on npm is so that other packages can use it, also outside of this repo.

Why 🤷

Mainly so we can have some swagger docs for others to consume and so we can generate types that are used in front and back ends. With these types we can type cast things like payloads to lambdas and responses from api calls in the front end.

How ⚙️

To make changes to the API types, simply edit the schema yaml, bump the version and run npm publish to get that new api out there.

What happens in the preversion step of deploying to npm is we run npm run build which in turn also runs npm run generate which makes the types. these types are then what others can consume.

Development mode 🚀

When developing locally you can just run npm run start to get a localhost version of swagger and see if it looks good to you.

How does it get into the aws bucket 🤔

When you run npm run deploy from root, it will build and package the api docs, that will then be deployed in the infra as code or 'infrastructure' package. In the infra package there is a lambda that will take the dist folder of the api docs and upload it to the bucket. This is done so that the bucket can be public and the api docs can be viewed by anyone.

Take close attention to the schema yaml file there are some things in it like 'API_URL' which are replaced with the URL of the stacks api when deploying the infra package.

What about version conflicts?

This is something we still need to solve. probably by just adding changeset to this package. I just did not get time for it yet and honestly they are not updated that often in parallel right now.