What is API documentation and what is Swagger/OpenAPI?

API documentation describes how to use an API — its endpoints, request/response formats, authentication, error codes, and examples. It is essential for developer adoption and reduces integration time. OpenAPI Specification (OAS), formerly known as Swagger, is the industry-standard format for defining REST APIs in a machine-readable YAML or JSON file. An OpenAPI document defines all endpoints, parameters, request bodies, response schemas, security schemes, and examples. Tools built on OpenAPI include: Swagger UI (interactive browser-based API explorer), Postman (import OpenAPI to generate a collection), code generators (client SDKs in any language), and mock servers. Maintaining an OpenAPI spec alongside code ensures documentation stays accurate and enables automated testing and contract validation.