OpenAPI

OpenAPI enables developers to define APIs in a consistent format, facilitating integration and documentation. It promotes interoperability between different systems and ensures better communication within the API ecosystem.

Use this profile to understand the building block briefly, place it in the model, and switch to the 360° assessment when needed.

Content type

Technology

Technical building block: can be automated, integrated, or operated.

Classification level

Element

Concrete cog in the system that works inside larger relationships.

Available perspectives

Open this building block directly in an already curated view.

360°

In brief

OpenAPI in brief

OpenAPI is a standardized format for describing HTTP APIs in a machine-readable way and sharing them across teams and toolchains.

Where does it come from?

OpenAPI refers to the standard family that grew from the Swagger specification, donated to the OpenAPI Initiative in 2015. It continued as an open, vendor-neutral approach to describing APIs.

The mental model

An OpenAPI description defines paths, operations, parameters, request and response schemas, and security requirements. The same description can drive documentation, mocking, tests, or clients. It is a contract; it does not implement the service automatically and only helps when it matches actual behavior.

Key building blocks

Description

Paths, operations, and data models make the expected API surface explicit.

Contract

Providers and consumers can refer to shared, machine-readable behavior.

Toolchain

Documentation, mocking, validation, and code generation can reuse one description.

When is it useful?

OpenAPI improves clarity and coordination in API development. Teams still need decisions about versioning, compatibility, security details, and keeping the specification aligned with implementation.

OpenAPI Specification – Swagger