Any programming language — API specification-related or otherwise — is only as good as the tools that support it. Without relevant and workable tooling, a community built around a given programming language will wither and die, as developers don’t have the affordances required to be productive human beings. They need the tools of their trade to get their jobs done.

Thankfully, OpenAPI Specification does not have a tooling problem — there are plenty of tools, and many are very popular. However, away from the core toolsets, easily finding the right and relevant OpenAPI tools can be a challenge. There is a perception that the OpenAPI Initiative could do more to help tooling makers publicize their wares and the features they support.

OpenAPI tooling repositories do exist. For example, there’s OpenAPI.Tools and awesome-openapi3. But, these projects are often reliant on the best efforts of maintainers and vary in their approach to validating the data they hold. The OpenAPI Initiative currently supports storing tools in the IMPLEMENTATIONS.md file in the OpenAPI specification repository, but this approach lacks scalability.

It’s also not just about publicity for tooling makers. The OpenAPI Initiative needs to work in lockstep with makers and users alike to understand their needs so the OpenAPI specification can genuinely evolve based on what the community wants to see in the spec. The OpenAPI specification can then actively complement what is most important to the community, providing the means for the efficient design, development, and delivery of APIs across the ecosystem.

Therefore, the OpenAPI Initiative (OAI), the governing body under the Linux Foundation, has kicked off a series of different workstreams, of which tooling is one. This workstream has several goals to help get in touch with the OpenAPI tooling makers in a much more interactive fashion, and our approach has three initial steps.

1. Federate and Merge Existing Repositories

The first step in our work, and where we are at the time of writing, is to create an “uber” toolset of the repositories mentioned above. The first cut of this already exists in the OAI Tooling repository. We have taken the content of OpenAPI.Tools and IMPLEMENTATIONS.md and the build mechanism of awesome-openapi3 and combined the two into a repeatable build process that is currently written to tools.yaml. The awesome-openapi3 approach works using GitHub topics. It searches for anything tagged as an openapi3 topic, which is an extensible mechanism for source data collection. This was implemented as query on the GitHub GraphQL API in awesome-openapi3, which we have extended using a pagination loop to collect up all results until exhausted:

  const query = `{
    search(type: REPOSITORY, query: "topic:openapi3", first: 100, ${recursor ? `after: "${recursor}"` : ''}) {
      edges{
        node {
          ... on Repository {
            url
          }
        },
        cursor
      },
      pageInfo {
        endCursor
      }
    },
    rateLimit {
      limit
      cost
      remaining
      resetAt
    }
  }`;

The build process merges the three data sources, combining the attributes of each into a unified view of each tool. Equivalent properties from each data source are aggregated based on some simple statistical functions. We’ve done this first to get a snapshot of the data already available in the ecosystem, and applied the metadata gathering approach from awesome-openapi3 to all the repositories across all the data sources.

Each repository we collect that is hosted on GitHub is then updated with key ecosystem information, including the number of stars, when it was last updated, the content of the README, and so on. This
provides a solid foundation for the next step of understanding the data therein. As the work progresses, we are looking at incorporating other source-code repository platforms such as GitLab and Bitbucket.

2. Analyze the Data

With a rich dataset in hand, the next step is to analyze the data to mine “what” is out there to view where any “gaps” might be. There are a number of goals here:

• Classification: Being able to classify the tooling is important as it will allow both the OpenAPI Initiative and users of the data to understand what is available. This then leads to an understanding of what is well-covered and what might be missing.
• Ecosystem health: Understanding the general health of the ecosystem is also important, which can be ascertained by scanning the repository metadata. How many active projects are there? What do the most popular projects have that others do not? These may seem like simple questions, but testing them based on empirical evidence is essential to address what’s important for the specification.
• Version support: Alongside the ecosystem’s health, there’s the health of version adoption. Which tools support what versions of OpenAPI? Are there any clues in the data on why popular tools might not readily upgrade to the latest version?

The expected result is to provide the data to drive decision-making around the specification and outreach to tooling makers and users. This will be incorporated into our build mechanisms discussed above, so we’ll constantly analyze what we find and improve our future implementation.

3. Publish the Toolset

The next step is relatively simple (and obvious). Users of the data can, of course, take a copy and use whatever tools they want to slice and dice. However, an enriched dataset will allow us to create a website that exposes the data with a friendly user experience that allows one to filter and search for tools. We’ll provide the means to query on the raw metrics, such as most repository stars, and on the classifications we generate in our analysis.

The project is not solely about creating a searchable website. We also want to leverage social channels for publishing tooling updates and gamify some of the mechanics. For example, we plan to use the data to create “leaderboards” of tooling — most stars, most-watched, and so on — and publish these on popular forums to drive interest in the tooling. The goal is to be an active participant in the tooling community, and the OpenAPI Initiative is well-positioned to carry out this kind of outreach.

How You Can Help

We still need to get some of the mechanics of how our outreach will work: How tooling makers can raise their concerns, how tooling users can flag their needs, and so on. For now, we want to ensure our dataset is as wide as possible, so it’s important for us to ask tooling makers to make our build process aware of your repository.

As discussed above, our approach is based on GitHub topics. To that end, we need to expand from the original openapi3 topic to cover all versions of the OpenAPI specification. We’ll therefore be supporting the following topics in GitHub for the foreseeable future:

• swagger
• openapi2
• openapi3
• openapi31

If you add one or more of these tags to your repository, we will start to collect your README and repository metadata and pull it into our analysis process. By doing so, you’ll be helping us to begin the process of understanding your needs more fully. And, you’ll be helping the OpenAPI community become even stronger as a result.

For absolute clarity, the goal here isn’t to become the tooling repository for the community for its own sake. We believe that pulling together the data will allow the OpenAPI Initiative to reach out to tooling makers more comprehensively, opening new communication channels and eliciting greater feedback on how the OpenAPI specification does and doesn’t work for them. This will then introduce a new feedback loop in the development of future versions of the specification. In taking this approach, we believe tooling makers and the OpenAPI Initiative can help the OpenAPI community become even stronger.