How Do Teams Enforce API Governance Rules Around OpenAPI?

[lucdev01234-png]

I'm interested in how teams maintain consistency when OpenAPI specifications are used across multiple APIs and development teams.

OpenAPI describes the API contract very well, but I'm wondering how teams handle organization-specific rules that go beyond the specification itself.

For example:

Required security schemes
Naming conventions
Required descriptions and examples
Deprecation policies
Consistent error responses
Required headers
Breaking-change detection
Documentation completeness

Do you normally handle these rules through OpenAPI linting and custom CI checks, or do you use a dedicated API governance tool?

I'm particularly interested in the boundary between OpenAPI validation and organizational API governance.

For example, if an API is perfectly valid according to the OpenAPI specification but violates an organization's internal API standards, where do you think that validation should happen?

I'd be interested to hear how teams using OpenAPI at scale approach this.

[nfroidure]

I built and use a tool to do this ( https://github.com/nfroidure/whook ) where the doc generates the routing of the API. I have a lil DSL to build schema with TypeScript that allow to create a set of schema to be reused across several projects with classic JavaScript imports. It is tied to projects with the exact same stack though.

[miqui]

Great questions.

Violations of an org's API standards should be shown asap: as the API is being drafted either manually (should not happen often) or immediately after generation by some AI and/or other automagic process/tool.

At least initially, OpenAPI spec linting (spectral, vacuum) either via a shared API platform where the API descriptions are managed or via APIOps style pipelines. However in both of these cases you have to do some degree of evangelism to get teams across your org to adopt this. IMHO, this is the hard part. Overall: "Good infra/governance becomes invisible when it works well".

[miqui]

Ensure that API descriptions are the source of truth. Otherwise this is just theatre.