philsturgeon
commented
2 years ago Hey @SensibleWood, we talked a while back about this project and openapi.tools, but if there's anything you'd like to talk about now I work with OAI directly please do reach out. Happy to help with this effort, although for now the plan is to keep openapi.tools going (as you said it's a bit opinionated and for now is trying a manual best effort to keep old, stagnant, or incomplete tooling out). This can be hoovered up into your system, de-duplicated, and peppered with more automated quality data!
LMK if you need anything to make any of it easier.
SensibleWood
This page defines the approach to the development of a tooling repository and engagement strategy for the OpenAPI Initiative, specifically in how to add tools to the directory. It reflects:
This proposal will evolve over time as the initial cut of the repository is established and tools ingested.
Problem Statement
It’s a fact that 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 the users of the language - developers - do not have the affordances required to be productive human beings.
OpenAPI does not have a tooling problem in the sense there is no tooling - there is lots of it. However, easily finding the right and relevant tools can be a challenge and it is perceived that the OpenAPI Initiative could do more to help tooling makers publicize their wares. It’s not that the repositories don’t exist - there’s https://openapi.tools and https://apis.guru/awesome-openapi3/ - but these may be considered opinionated in their construct or coarse-grained in their data selection. There is also limited means to drive quality in the data, as they either work on snapshots based on automated searches or best efforts of maintainers with limited time available. The current mechanism of storing tools in the IMPLEMENTATIONS.md in the specification repository is also not fit-for-purpose, based on the number of pull requests that require merging.
The goal of the Tooling workstream is therefore to address by developing a dedicated repository for tooling that can become a ubiquitous community resource with the means to provide curated content.
To that end there are a number of specific objectives in its creation:
These objectives are expanded on below.
Federate and merge existing repositories
The first objective is to bring together the data that already exists in the community. It makes no sense to start from scratch given the considerable collateral that we already have from existing resources. The design approach is one of “loose-coupling”, where we can draw from existing repositories on an ongoing basis without affecting their presence or modus operandi.
The existing resources in scope are as follows (and already mentioned above):
These will be combined into a single, attributed list in the Tooling repository and, in the case of https://openapi.tools continue to be merged into the near future. There are two significant advantages to this approach:
The table below shows the in scope repositories for the first iteration:
The “Merge” approach for ingesting https://openapi.tools will be extensible, in that it will be future-proofed to allow us to bring other repositories and sources of information as we uncover them. This will allow us to always build on the existing community efforts, hopefully extending buy-in to our unified repository.
Analyze and curate content
The combined dataset will be housed in the new Tooling repository and be updated on a daily basis with changes from federated repositories using (most likely) GitHub actions as the build tool. Individual contributors will also be able to contribute to the repository where required (for example, where the tool is commercial and closed source).
The Bayesian analysis and GitHub metrics (Stars, etc.) will then be expanded to incorporate more metadata and extended across all repositories in an effort to ensure consistent categorization. This will help drive qualitative analysing of the data to ensure that anything that turns out irrelevant can be filtered (for example: tagged repositories with boilerplate code or limited community value, dead repositories, etc.)
Mopping up any failures in the automated analysis will be undertaken manually.
Publish centrally
The final objective - publishing the information for the use of the community - should be straightforward in terms of look-and-feel, i.e.:
However, this will be accompanied by filtering mechanisms that will make the most of metadata we can gather, viz.:
The power of the new Tooling repository lies here: exploiting the available metadata to ensure our efforts enable the OpenAPI community to make informed decisions in their choice of tooling.