Introducing Framna Docs

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.

Centralising OpenAPI documentation

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:

• GitHub repository: Framna Docs can load OpenAPI specifications from both private and public GitHub repositories. We maintain separate repositories for each project’s OpenAPI specifications.
• Remote location: Framna Docs can also load OpenAPI specifications from remote locations via a link, allowing us to centralise documentation from partners and third parties.

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.

Facilitating spec-driven development

When documenting APIs using the OpenAPI standard, there are generally two approaches:

• Code-driven development: Write the source code first and then create documentation to describe its behaviour.
• Spec-driven development: Define the contract between the backend and client in the OpenAPI specification first, then write the source code to match it.

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.

• Code-driven development: Developers write the source code manually, and the OpenAPI specification is generated from the code.
• Spec-driven development: The OpenAPI specifications serve as the foundation, and the source code is generated from these specifications.

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.

Unlocks powerful features built on top of GitHub

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:

• Version control: Like any other files on GitHub, all our documentation is always kept under version control, ensuring changes are tracked and manageable.
• Easy collaboration: Most developers are familiar with GitHub, making collaboration through pull requests simple and efficient.
• Parallel documentation: Framna Docs reads OpenAPI specifications from all branches and tags within a repository, allowing teams to document features in parallel on separate branches and tag different versions of the documentation.
• Restrictive access control: Users can only access documentation in GitHub repositories they already have access to, maintaining secure and restrictive access.
• Support for multiple organisations: As Shape becomes Framna, a company with several GitHub organisations, Framna Docs allows users to load documentation from any organization they have access to simply by logging in with their GitHub account.
• Support for guest users: It's easy to provide partners or third parties with access to specific projects on GitHub. All it takes is adding them as external collaborators.
• GitHub Actions Integration: We can leverage GitHub Actions for advanced operations, like linting OpenAPI specifications on every pull request.

Get started with Framna Docs

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 💃🕺🤘