The need for good API documentation
Every developer knows that documentation is an essential aspect of API adoption. With comprehensive API documentation that explains all features, developers can quickly adapt and integrate them into other applications. In addition to increasing API adoption, good documentation also improves the development process in several ways:
- Simplified project management
In many projects, tasks are broken down as "Jobs to be done". Using an API to model a job task is common across several projects. Without a well-designed and documented API, you and your team members will be forced to spend more time copying data between tools and completing tasks.
- Improved development velocity
Good documentation is a perfect way for app builders across your organization to self-serve their application needs. It makes information more accessible and easier to find, empowering new members to figure things out on their own. They can easily see how to work with APIs and quickly get up to speed on projects.
- Better organizational consistency
Good API documentation fosters better consistency and standards within an organization. Just like designers and writers have a style guide for content, good API documentation serves as the style guide for developers using an API.
Why you should auto-generate API documentation
Well-written API documentation can make your APIs look and feel professional, but it can be a time-consuming task to maintain manually. Throughout the life-cycle of your application, the API documentation needs to be kept up to date. For example, if you create a new table, or change the schema of an existing table, you will need to update the documentation accordingly. Thanks to Supabase's auto-generated documentation, this can now be done easily. You can now automatically update documentation pages to reflect application changes and reduce the effort needed to keep up with documentation drift.
Stripe is a great example of an organization that has excellent API documentation and is highly regarded by API consumers. Did you know that they also make use of auto-generated documentation?
Getting started with auto-generated Supabase documentation
Supabase is built for developers and you can get started for free using your existing Github account. Once your Supabase account is set up, you will be able to access the Supabase dashboard. From here, go to All Project > New Project.
Give your project a name and set the database password. You can also choose the region and adjust the pricing plan based on the requirements of your project.
Once you create a new project, you will see the services offered by Supabase which includes a hosted database built on top of PostgreSQL. You can start creating tables in your database by clicking the Table editor button.
Here you can create your own tables and start defining your table schema.
Once you create a table, you can then add rows to the tables using the Table Editor.
If you create tables or update table schemas, API documentation will be auto-generated. You can then view the auto-generated API documents by going to the API section from the left menu.
The view on the right shows you how you can connect to your Supabase project from within Node.js applications using the createClient class from the supabase-js npm package.
For authentication, you can find your Supabase API keys by going to Settings > Project Settings > API.
Once your application has been created, you can use it to interact with your database tables. The table-specific documentation that is auto-generated gives you code snippets for the operations available. To view table-specific API documentation, go to API > API Docs > Tables and Views > {YOUR_TABLE}
As soon as you select the table to view, you'll see the schema definition. You can even add additional descriptions to your table fields to improve the documentation even more.
The section on the right contains the auto-generated documentation for your table. These are code snippets that can be plugged into the Supabase client application from the previous step to perform database operations. The first set of code snippets shows you how to select all values from the table for a specific field.
Scrolling down further, you can see the auto-generated documentation that lists code snippets for other CRUD operations using the Supabase client.
If you're building a real-time application, the "Subscribe to changes" section might be interesting. The code snippets show how you can subscribe to all or specific events. These events are triggered whenever changes are made to the table.
Supabase also auto-generates CURL requests for CRUD operations to run against your tables. This gives users a way to quickly interact with their tables if you're using the Linux command line.
Conclusion
The importance of creating good API documentation can't be stressed enough, and
there's no need to try to reverse engineer code written by others in order to create documentation. With Supabase's API doc auto-generation, you can skip the tedious task of creating documentation and focus more time on building your application.
It's no surprise why developers are drifting to the Supabase way!
Now, become a Supabase developer today by starting a new project on our free tier
Oldest comments (0)