It takes work to strengthen the awareness engineering teams have surrounding OpenAPI. OpenAPI is often seen as simply a configuration for producing API documentation, or possibly for generating client side SDKs, but it is the alignment between backend API code and the API gateways which can have the greatest impact. The strength of your API, as defined by a complete and accurate OpenAPI, which is used to configure your API gateway is the most important thing you can be doing to realize API governance.
An OpenAPI YAML or JSON artifact describes the surface area of your HTTP API and is often used as the configuration of a new or existing API gateway configuration. Most API gateways allow you to import an OpenAPI 3.x document to deploy, distribute, or publish your API to a specific staging environment. It is this configuration of the API gateway that will help ensure the backend code for your API as described by an OpenAPI is truly reflected or enforced by the gateway—this is how all the technical details of your OpenAPI shape the runtime for your API.
The code for your API is just one source of truth, and the accuracy and completeness of your API gateway at runtime is another extension of that truth, which is articulated via your OpenAPI, and then used to continue sharing that truth downstream via API documentation and SDK generation. When you spend your time heads down writing code, it is important to remember that your OpenAPI isn’t a byproduct just to get documentation and SDKs, and it acts as the configuration of your API to the world, aligning your code with what applications will actually be accessing via your API gateway.
A lot of attention is spent on OpenAPI as documentation, and maybe secondarily code generation. This is why you see so many people overlook the role it plays in runtime, automation, and even applications. Most just see OpenAPI as an output for a single experience in the API lifecycle, when in reality in aligns across multiple experiences from design to develop to runtime, and down stream for your consumers via documentation, SDKs, clients, other experiences. Without this alignment, governance of a single OpenAPI for a single experience won’t get you very far, and there will be a lot more friction with every change.
