This lesson's interactive features are locked, please to keep using them
Documentation
As far as creating documentation goes, there are 2 main approaches:
Manually write documentation
Use a tool to generate documentation
Obviously, the first approach is easier to get going with if you have a small API, but as the system grows, it can be really hard to keep the documentation up to date.
Incorrect documentation is worse than no documentation.
At least when there is no documentation, your clients will reach out and ask for clarification. When the documentation is incorrect, it can lead to a lot of wasted time and frustration.
Manually Writing Documentation
When I've worked on smaller teams, we've generally opted to write our documentation in Markdown files and host them on GitHub. This is a great way to get started because Markdown is a simple format that is easy to write and easy to read.
Automated Documentation Generation
I've also written and consumed APIs that have used:
GraphQL (not RESTful, but still a networking API)
Godoc (which only works for REST APIs if you provide an SDK)
Postman (only useful if your team all uses Postman as their HTTP client)
And with LLMs, there are also now trivial ways to use AI to generate simple markdown documentation directly from your backend code.
Okay, but What Should I Do for Now?
I recommend personally writing documentation for your projects in Markdown files and storing them alongside the rest of your code in Git. Your project's README.md file is a great place to start, but it's also common for the README.md file to link to a /docs folder that contains more detailed documentation. The benefits are:
It's easy to get started (no need to install any additional tools)
The documentation lives alongside your code, so it's easy to keep it up to date
You'll learn Markdown, which is a great skill to have
GitHub/GitLab will render your Markdown files for you, so your docs will look great