Business analysis glossary
OpenAPI Specification
What it is
The OpenAPI Specification is a standard format, written in JSON or YAML, for describing a REST API: its endpoints, methods, parameters, request and response bodies, status codes and security. Tools such as Swagger read it to produce interactive documentation, test calls and code.
Why it matters
An OpenAPI file is the single source of truth for an API contract, shared by developers, testers and partners. Analysts who can read one can check that the API matches the requirements, spot missing error responses and answer partner questions without waiting for a developer.
Example
Reviewing the OpenAPI file for the returns API, the analyst notices the create return endpoint lists only 201 and 400 responses. The requirements say a return outside the allowed window must be refused with a clear reason, so she asks for a 422 response with an error message and it is added before the build starts.