What is OpenAPI / Swagger?

What Is OpenAPI?

OpenAPI describes a REST API as a standard contract: which endpoints exist, which parameters they accept, what responses they return, and how authentication works. The contract is usually stored as a YAML or JSON file.

The name Swagger is still used in the ecosystem because Swagger tools can read an OpenAPI file and generate visual documentation, test consoles, or client code. OpenAPI is the name of the standard itself.

What an OpenAPI File Contains

• Paths: Endpoint addresses such as /orders/{id}
• Methods: HTTP operations such as GET, POST, PUT, and DELETE
• Parameters: Query, path, header, and cookie parameters
• Request body: JSON schemas and required fields
• Responses: Status codes, example responses, and error formats
• Security schemes: API key, OAuth2, or bearer token definitions

The file is more than documentation. It can drive mock servers, SDK generation, contract tests, gateway validation, and Postman collection generation.

Business Use

OpenAPI reduces ambiguity in customer integrations, mobile backends, payment and shipping connections, and service contracts between teams. A frontend team can build against a mock API before the backend is complete; an integrating customer can see which fields are required.

In REST API projects, the OpenAPI file should be versioned with the code. Otherwise documentation quickly drifts away from real API behavior and integration errors increase.