Water Restrictions API Docs
External documentation for the Water Restrictions API. Built with Docusaurus and uses a Scalar integration to provide an API playground for developers.
With the Water Restrictions API up and running, I wanted an easy way for developers to explore its endpoints and concepts. I’ve used Docusaurus in the past for documentation and decided to use it again for this project.
A major advantage is its Scalar integration, which let me embed an interactive API playground into the docs. This gives developers an easy way to try out the API. Plus, because it pulls directly from the OpenAPI spec generated by the API, the docs automatically stay up to date with any changes.
Implementation ⚙️
Tech stack
This project mostly uses my standard platform setup. Given this is a static site there are some differences, though. There was no need for a backend or database as all of the content is in markdown files in the repo itself. Docusaurus uses these files to generate the site.
Frontend:
- Docusaurus - Documentation framework
- Scalar - API playground integration
Infrastructure:
- Terraform - Infrastructure as code for managing the project’s resources
- GitHub Actions - CI/CD for automated deployment
- Cloudflare Pages - Hosting
Documentation Site 📚
With a bit of styling, the site came together really nicely. Adding support for dark mode was also straightforward.
The docs are focused on how the API works and how it’s maintained, rather than diving into low-level technical details. Those specifics are handled by the auto-generated API reference, generated directly from the API’s OpenAPI spec. This keeps the technical documentation closely aligned with the API itself and avoids duplication.
Scalar Integration & API Playground ⚡
Scalar is a key part of the documentation. On each page load, it fetches the latest OpenAPI spec directly from the Water Restrictions API and generates the reference in real time. This ensures the docs are always in sync with the latest changes and provides an interactive playground where developers can test endpoints directly in the browser.
While fetching the spec live could theoretically become a performance bottleneck under heavy traffic, I don’t expect that to be an issue at this stage. If it does become a problem, I can switch to generating the spec at build time and serve it from a static location (like an AWS S3 bucket) instead.
A nice bonus is that Scalar inherits the site’s styling, making it feel like a seamless part of the documentation.
As for the “API playground” itself, Scalar provides a fully interactive interface for testing real endpoints — live requests can be made directly from within the docs.
