# API Governance, Catalogues and AsyncAPI — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/p-governance

> Scale API practices across teams with style guides, catalogues and event descriptions.

## Many APIs, one experience

As organisations grow to dozens or hundreds of APIs, **governance** keeps them coherent without slowing teams down. Ingredients: an **API style guide** (naming, pagination, errors, versioning, security) expressed as **lint rules**; **reusable components** shared across APIs (error schemas, pagination envelopes, common parameters), published as a versioned library referenced with `$ref`; an **API catalogue** or developer portal (Backstage, SwaggerHub, Redocly, API gateway portals) listing every API with its owner, lifecycle stage, documentation and SDKs; **design reviews** for public or cross-team APIs; and **lifecycle** policies for deprecation and sunset. Event-driven interfaces need the same care: **AsyncAPI** describes channels, messages and their schemas for Kafka, RabbitMQ, MQTT and WebSockets, with similar tooling for docs, code generation and linting. Governance works best as a **paved road**: templates and automated checks that make the right thing easy, rather than manual approval gates.

## Sharing components across APIs

A central, versioned library of common definitions referenced by each API.

```yaml
# common/v1/components.yaml (published, versioned)
components:
  schemas:
    Problem: { $ref: './schemas/problem.yaml' }
    Money:
      type: object
      required: [amount, currency]
      properties:
        amount: { type: string, pattern: '^\d+\.\d{2}$' }
        currency: { type: string, pattern: '^[A-Z]{3}$', examples: [INR] }
  parameters:
    Limit: { $ref: './parameters/limit.yaml' }
    Cursor: { $ref: './parameters/cursor.yaml' }

# orders-api/openapi.yaml
components:
  schemas:
    Order:
      type: object
      properties:
        total: { $ref: 'https://specs.example.com/common/v1/components.yaml#/components/schemas/Money' }
  responses:
    ValidationProblem:
      description: Invalid request
      content:
        application/problem+json:
          schema: { $ref: 'https://specs.example.com/common/v1/components.yaml#/components/schemas/Problem' }
```

## Building codes for a city

A city does not inspect every brick, but it publishes building codes, offers standard designs and checks key points automatically. API governance works the same way: shared rules and components, with automation doing most of the checking.

**Quiz:** Which specification describes event-driven, message-based APIs in the way OpenAPI describes HTTP APIs?

- [ ] GraphQL SDL
- [x] AsyncAPI
- [ ] WSDL
- [ ] JSON:API

*Answer:* AsyncAPI. AsyncAPI describes channels and messages for brokers and other asynchronous protocols.