More Examples of using GitHub to Manage Your OpenAPI

I have found thirteen more solid examples of API providers using GitHub to manage their OpenAPI and related artifacts. I am regularly finding these as I am profiling APIs, and rather than just write a blog post each time I figured I’d store as YAML, and keep adding them in batches every couple of weeks.

You can find all of the API providers who are using GitHub via a YAML file, or here via this post.

As I add each provider to the list I also have created a separate YAML file for the properties I find supporting each GitHub repository, providing a pretty interesting checklist to consider.

  • Authentication - Providing details on how to authenticate with an API.
  • Change Log - There is the regular GitHub changelog markdown for repository.
  • Code Generator - Provide you with the ability to generate code.
  • Collections - Postman collections were oftentimes part of the build output.
  • Contact - I found some contact information on some of the repositories.
  • Contributing - There is the standard contributing README for GitHub repos.
  • Directory Structure - A few of them would provide an overview of folders.
  • Documentation Generator - Publishing markdown or other docs.
  • Extensions - Several providers shared the OAS extensions they put to use.
  • GitHub Actions - There were GitHub actions to automate the CI/CD of OpenAPIs.
  • Historical - Providing historical links to previous versions of an OpenAPI.
  • Issues - The GitHub issues are used as a feedback loop for the OpenAPI definitions.
  • JSON - Others would publish only a JSON, or a JSON to accompany the YAML.
  • JSON Schema - Storing your JSON Schema separate from OpenAPI is compelling.
  • Licensing - There was always licensing for the OpenAPI specs and the code.
  • Limitations - I saw explanations of the limitations of each of the OpenAPIs.
  • Make File - Some provide make files that would automate various builds.
  • Maturity - Occasionally you would see preview and other maturity dimensions.
  • Modular OpenAPI - Digital Ocean took a very modular approach to theirs.
  • Multiple OpenAPI - Others would break down and publish multiple OpenAPIs.
  • NPM Package - Providing an NPM package for your OpenAPI and supporting resources.
  • OpenAPI Editor - Linking to an OpenAPI editor to support work.
  • OpenAPI Generator - Allowing you to generate the OpenAPIs.
  • Postman Collections - Provided one or more Postman Collections to go with your OpenAPI.
  • Quality Badges - There were badges showing the health of each build.
  • README - They put a variety of efforts into their README for consumers.
  • Repository - They all had a dedicated GItHub repository for their OpenAPIs.
  • Reviews - Microsoft had the ability to get a review of the OpenAPI being added.
  • Security - Details regarding the security of an API, and what is required.
  • Server Environments - Providing a list of servers available to call when using an API.
  • Software Development Kits (SDKs) - Provide SDKs that are generated from OpenAPI in multiple languages.
  • Single OpenAPI - Some of them would just publish a single OpenAPI to rule them all.
  • Spectral - There were Spectral rules, as well as build processes using them.
  • Status - There were various mechanisms for communicating the status of OpenAPIs.
  • Support - Some providers were explicit about the support they would provide.
  • Testing - Sometimes you could find test suites to make sure OpenAPI checked out.
  • Versions - Sometimes they clearly broke out various versions of the OpenAPI.
  • Workflows - Offering workflows built on an API with code, or other artifact.
  • YAML - Some of them would also provide a YAML version of their OpenAPI.

The list of properties really overlaps with the properties of an API portal and APIs.json index, but with OpenAPI as the center piece. Some of these repos are more about just making the OpenAPI available, while others clearly have a build apparatus around them.

I will keep setting the interesting ones aside. I don’t think every OpenAPI in a GitHub repo is worth showcasing, but when you find API providers who have invested more into their approach, you find there is often a lot to learn from them.