What is OpenAPI Specification (OAS)?
OpenAPI Specification (OAS), also referred to as Swagger Specification, is a standard, programming language-agnostic way of documenting REST APIs so that the documented service can be used by humans and machines. OAS helps developers and technical writers produce better API documentation. It can also be used by a documentation generation tool like
Structure of an Open-API document
An Open-API spec can be written in JSON or YAML. Below is a sample spec in both YAML and JSON.
{"openapi": "3.0.0","info": {"title": "Todo API","description": "A complete end-to-end API specification for a Todo Application.","version": "0.1.0"},"servers": [{"url": "http://api.example.org/v1","description": "Production server"},{"url": "http://staging-api.example.org","description": "Internal staging server"}],"paths": {"/todos": {"get": {"summary": "Returns a list of todos.","description": "This list should not be used as a substitute for making lists","responses": {"200": {"description": "A JSON array of todo items","content": {"application/json": {"schema": {"type": "array","items": {"type": "object"}}}}}}}}}}
The basic structure consists of the version number, the title, spec version, server info, and the various API endpoints defined within paths. Open-API allows one to reference spec defined in another file.
Output of OAS
An Open-API Spec can be used to generate a web page containing callable REST endpoints.
This is especially useful for teams with separate frontend and backend divisions. The backend team can easily update the specification that the frontend team will implement.
