What is OpenAPI ? And Why should you even use it?

May 2, 2026

What is OpenAPI?

The OpenAPI Specification (OAS) is a standardized format for describing HTTP APIs. With OAS, you can outline with great detail your API's operations, the structure of request and response payloads, and the authentication requirements.
OAS is language-agnostic; meaning it doesn't describe how your API is implemented or what technologies your client would use to make requests. Rather, OAS is about describing the contract of the API. What does your API expect from the client? And what will it return if the correct conditions are met?

What does an OpenAPI spec file look like?

We'll use the example below to show what OpenAPI is capable of describing. It describes part of an online store's API and centers around the "Products" resource. JSON or YAML can be used with OpenAPI, but I'll use YAML in this article for its readability.

openapi: 3.2.0
info:
  title: OnlineGroceryStore
  version: 1.0.0
paths:
  /products:
    get:
      summary: List Products
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                required:
                  - products
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Products'
      operationId: list-products
      parameters:
        - schema:
            type: string
          name: name
          in: query
    post:
      summary: Create Product
      responses:
        "201":
          content:
            application/json:
              schema:
                type: object
                required:
                  - product
                properties:
                  product:
                    $ref: '#/components/schemas/Products'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: create-product
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Products'
  /products/{productId}:
    get:
      summary: Get Product
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                required:
                  - product
                properties:
                  product:
                    $ref: '#/components/schemas/Products'
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-product
    put:
      summary: Update Product
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/Products'
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: update-product
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Products'
    parameters:
      - schema:
          type: string
        name: productId
        in: path
        required: true
components:
  schemas:
    Error:
      title: Error
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    Products:
      title: Products
      type: object
      required:
        - id
        - name
        - sellingPrice
        - weight
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
        description:
          type: string
        sellingPrice:
          type: number
        weight:
          type: number
  securitySchemes:
    auth:
      type: http
      name: Bearer Auth
      scheme: bearer
security:
  - auth: []

"Endpoints" are described by a path-method pair. For example, the "List Products" endpoint is identified by the path /products and the HTTP method get.

paths:
  /products:
    get:
      summary: List Products

Requests and responses are set using the requestBody and responses fields. We can clearly see in the example below the endpoint expects the request body to be be in JSON format and match the "Product" component (more on that in a second). The endpoint may respond with a "201 - Created" status code returning a "Product" component, or a "400 - Bad Request" status code with an "Error" component.

paths:
  /products:
    post:
      summary: Create Product
      operationId: create-product
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Products'
      responses:
        "201":
          content:
            application/json:
              schema:
                type: object
                required:
                  - product
                properties:
                  product:
                    $ref: '#/components/schemas/Products'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

One of the very powerful aspects of the OpenAPI specification is creating standardized components that can be used throughout your spect file. Instead of redefining how your "Product" component (I refer to them as models) looks like in every endpoint, you can define it once under components/schema and reference it wherever you need it.

components:
  schemas:
    Products:
      title: Products
      type: object
      required:
        - id
        - name
        - sellingPrice
        - weight
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
        description:
          type: string
        sellingPrice:
          type: number
        weight:
          type: number

readOnly and writeOnly Properties

You'll notice in the OpenAPI example spec that the "Product" model is used in the request body and response body when creating a product. Since the "Product" model has an id property, it would be safe to assume the client must provide a value (which is definitely odd).
The OpenAPI specification has many interesting features to make Api design effortless. One of those super powers is the readOnly and writeOnly properties. By setting id to be readOnly, per the OpenAPI specification, it means the property should be included in responses, but not in request bodies. Likewise, for writeOnly, the property should be included in request bodies but not in responses.

And lastly, security! How can we forget security. Thankfully, OpenAPI has a powerful way to describe authentication requirements. It supports describing various authentication schemes such as API keys, HTTP authentication, OAuth2, and OpenID Connect. You can define your security schemes under the components/securitySchemes section and reference them in your endpoints.
You can go as far as either setting global authentication requirements, or specific per-endpoint requirements.

components:
  securitySchemes:
    auth:
      type: http
      name: Bearer Auth
      scheme: bearer
security:
  - auth: []

Ok, but how is OpenAPI useful in API development?

There are 3 primary benefits of using OpenAPI in your API development process.

1. Align your team around a single source of truth

API development is a collaborative effort. You have backend engineers implement the API, frontend or client engineers integrating with the API, and potentially non-technical stakeholders who need to understand the API's capabilities for customer and third-party integration partners. Therefore, it is critical to point to a single resource as the correct outline of the API contract. Otherwise, you may end up with spreadsheets or scattered markdown articles that must individually be maintained (and you may not even know which one is the real truth).

2. Accelerate API development with tooling

The OpenAPI specification is machine readable. That means you can leverage many tools that can parse your OpenAPI spec file and generate code, documentaiton, or tests. For example, I've used Hey API to develop client SDKs for web and mobile clients immediately. No longer did I have to worry about if I've already updated the integration layer, or if the spelling of properties are correct. I had a guarantee that as long as my OpenAPI spec file was up to date, the generated SDKs would be correct.

Another excellent tool is Stoplight Elements. If you have an OpenAPI spec file, Elements will automatically generate API documentation for you.

3. Think about your API before writing code (Design-First)

Whether you are building a house, a car, or an API, designing the project ahead of implementation is critical. If you jump into writing code before thinking about the design of your API, you will likely go back and refactor your work as you discover the many ways it doesn't meet client requirements.

By use OpenAPI before writing code, you are forced to think of the shape of your API early. You can then socialize the design with your team and gather feedback so that once implementation begins, you are much less likely to make (an expensive) change.

Where to start?

There are many OpenAPI tools in the ecosystem to help you get started. Stoplight Studio is one such tool that provides a visual interface for designing, documenting, and testing your APIs. Swagger also has a suite of tools for working with OpenAPI, including the Swagger Editor for designing your API and Swagger UI for generating documentation.

Although there is a rich ecosystem, I felt it was lacking a great visual designer to help me craft APIs without writing raw YAML or JSON. Although Stoplight is an excellent tool, it hasn't seen much development after being acquired by Smartbear. This is why I built Restly. Although new, we are quickly expanding it's featureset to offer a powerful API designer that can help you from start to finish. We have plans to integrate Stoplight Spectral for API linting, create a CLI to integrate with CI/CD workflows, and more more!

Try Restly for Free