At this year’s FramnaCon, our first company-wide conference that took place in Obonjan, Croatia, we open-sourced Framna Docs, an internal tool for centralising API documentation and facilitating spec-driven development.
As an agency collaborating with numerous partners, we have developed—and will continue to develop—many mobile apps and backend services that rely on APIs to exchange data. Over the years, we've noticed that API documentation often becomes fragmented across various platforms like Confluence, Notion, Postman, GitHub, and even Google Sheets. This fragmentation makes it challenging to find the right documentation when needed and leads to inconsistencies in format, making it even harder to navigate and understand the documentation.
We set out to tackle this challenge with Framna Docs in October 2023 and have been using it daily at Shape for almost a year. Today, we’re excited to announce that Framna Docs is now open-source.
With Framna Docs, we’ve centralised our documentation, making it easier for developers to find the information they need. We've also migrated all our existing documentation—and will write all new documentation—in OpenAPI specifications, a widely recognised standard for describing HTTP APIs.
Framna Docs showing a list of projects and the documentation for the selected projected.
Using OpenAPI as a standard makes it easy to share our API documentation with partners and allows Framna Docs to utilise OpenAPI specifications from partners or third parties. Framna Docs can handle documentation from two main sources:
We leverage the open-source tools Swagger, Redocly, and Stoplight to visually present OpenAPI specifications. Since many developers are already familiar with these tools, integrating them into Framna Docs not only reduces our workload but also gives developers the flexibility to choose the OpenAPI viewer they prefer.
The three OpenAPI viewers supported by OpenAPI. From left to right: Redocly, Swagger, and Stoplight.
When documenting APIs using the OpenAPI standard, there are generally two approaches:
The best approach depends on what you want as your source of truth: the source code or the documentation (as defined by the OpenAPI specification).
At Shape, we use the spec-driven development approach on many of our projects. This method allows backend and client-side developers to collaborate on the API contract, ensuring the API is well-documented and enabling parallel development from the start.
By involving various team members—backend developers, frontend developers, and technical leads—in writing the contract between the client and backend, we can better account for multiple aspects of the product, such as performance, backward compatibility, and the roadmap. This approach not only results in better products built more quickly, but it also fosters knowledge sharing, strengthening both the team and the individuals within it.
When working with OpenAPI specifications, it's natural to consider how code generators can accelerate development and enhance system reliability. The role of code generators varies depending on whether you choose a code-driven or spec-driven approach.
Introducing a code generator is an optional but powerful step. At Shape, we aim to generate as much of our networking code as possible from OpenAPI specifications and have had great success doing so in our Swift codebases. This approach helps us reduce boilerplate code, speed up development, and ensures that our Swift codebase adheres to the contract established with the backend.
Framna Docs facilitates a spec-driven workflow by requiring OpenAPI specifications to be stored in GitHub repositories. This setup allows us to use native Git and the PR review process to collaborate on specifications. Additionally, using GitHub enables us to enforce branch protection rules that require reviews from multiple team members before changes are merged, as well as set up linting checks to validate the OpenAPI specifications.
Additionally, Framna Docs includes a GitHub bot that comments on pull requests that modify one or more OpenAPI specifications in the repository. This feature allows reviewers to preview the changes directly in the Framna Docs web app.
The GitHub bot comments on a pull request to highlight several OpenAPI specifications were modified.
When visitors open Framna Docs, they are prompted to sign in with their GitHub account. This allows Framna Docs to load documentation from both private and public repositories the user has access to. Framna Docs doesn’t store OpenAPI specifications itself; instead, it reads them directly from GitHub and from remote sources defined in a configuration file that resides within the repository.
The Framna Docs login page.
Building Framna Docs on top of GitHub was a key design decision that offers several advantages:
Framna Docs is a self-hosted and open-source platform. If you’d like to learn more about hosting Framna Docs yourself, we encourage you to have a look at the source code on GitHub as well as the wiki which describe how to setup and deploy Framna Docs.
Lastly, it seems no blog post is complete these days without a mention of AI. So, here’s ours: we used Suno, a generative artificial intelligence music creation service, to compose this musical theme for Framna Docs 💃🕺🤘