What are examples of OpenAPI schemas? #

OpenAPI, formerly known as Swagger, is a standard for defining RESTful APIs in a way that allows both humans and computers to understand the capabilities of a service without accessing its source code. This format is language-agnostic and ensures that APIs are described in a way that’s both machine and human-readable. An OpenAPI schema defines the endpoints, parameters, request and response formats, security considerations, and any other details crucial to implementing or consuming the API.

In this article, we will examine several examples of OpenAPI schemas across various use-cases and industries.

Simple API for a To-Do List Application #

A to-do list API is an excellent starting point for understanding the basics of OpenAPI. It involves typical CRUD (Create, Read, Update, Delete) operations.

openapi: 3.0.0
info:
  title: Simple ToDo List API
  version: 1.0.0
paths:
  /todos:
    get:
      summary: List all to-dos
      operationId: listTodos
      responses:
        '200':
          description: A JSON array of to-dos
          content:
            application/json: 
              schema: 
                type: array
                items: 
                  $ref: '#/components/schemas/ToDo'
    post:
      summary: Create a new to-do
      operationId: createTodo
      requestBody:
        description: To-do to add
        required: true
        content:
          application/json:
            schema: 
              $ref: '#/components/schemas/NewToDo'
      responses:
        '201':
          description: To-do created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToDo'
  /todos/{id}:
    get:
      summary: Get a to-do by ID
      operationId: getTodoById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single to-do
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/ToDo'
        '404':
          description: To-do not found
    put:
      summary: Update a to-do
      operationId: updateTodo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Updated to-do
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewToDo'
      responses:
        '200':
          description: To-do updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToDo'
        '404':
          description: To-do not found
    delete:
      summary: Delete a to-do
      operationId: deleteTodo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: To-do deleted
        '404':
          description: To-do not found
components:
  schemas:
    ToDo:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        completed:
          type: boolean
    NewToDo:
      type: object
      properties:
        title:
          type: string
        completed:
          type: boolean
          default: false

In this schema:

/todos endpoint supports GET and POST methods.
/todos/{id} endpoint supports GET, PUT, and DELETE methods for specific to-do items by ID.
It defines common response codes such as 200, 201, 204, and 404.
ToDo and NewToDo are defined in the components section to avoid redundancy.

API for a Blogging Platform #

A more complex example might involve a blogging platform. This API will have endpoints for users, posts, and comments.

openapi: 3.0.0
info:
  title: Blogging Platform API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      responses:
        '200':
          description: A JSON array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{userId}:
    get:
      summary: Fetch a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
  /posts:
    get:
      summary: List all posts
      operationId: listPosts
      responses:
        '200':
          description: A JSON array of posts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
  /posts/{postId}:
    get:
      summary: Fetch a post by ID
      operationId: getPostById
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          description: Post not found
  /posts/{postId}/comments:
    get:
      summary: List comments for a post
      operationId: listComments
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
    Post:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        body:
          type: string
        authorId:
          type: string
    Comment:
      type: object
      properties:
        id:
          type: string
        body:
          type: string
        postId:
          type: string
        authorId:
          type: string

In this schema:

Users, posts, and comments each have their own endpoints.
The components section minimizes redundancy.
Endpoint paths are parameterized for resource identification.

E-commerce API Example #

An e-commerce API will handle products, orders, and customers. This schema will be more complex, including search parameters and nested resources.

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
paths:
  /products:
    get:
      summary: List all products
      operationId: listProducts
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: priceMin
          in: query
          schema:
            type: number
        - name: priceMax
          in: query
          schema:
            type: number
      responses:
        '200':
          description: A JSON array of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary: Fetch a product by ID
      operationId: getProductById
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
  /orders:
    post:
      summary: Create a new order
      operationId: createOrder
      requestBody:
        description: Order details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{orderId}:
    get:
      summary: Fetch an order by ID
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        price:
          type: number
    NewOrder:
      type: object
      properties:
        productIds:
          type: array
          items:
            type: string
        customerId:
          type: string
    Order:
      type: object
      properties:
        id:
          type: string
        productIds:
          type: array
          items:
            type: string
        customerId:
          type: string
        status:
          type: string

In this schema:

GET /products supports filters via query parameters.
POST /orders allows for the creation of new orders.
The structure supports more complex business logic found in e-commerce platforms.

Conclusion #

OpenAPI schemas provide a standardized way to describe RESTful APIs, making it easier to define, develop, and consume services. From simple to-do lists to complex e-commerce systems, these schemas allow for a clear and concise representation of the full API lifecycle. This not only aids in building robust APIs but also ensures that documentation, client libraries, and other tooling can be auto-generated, streamlining development processes.

For further information on OpenAPI, I recommend visiting the official OpenAPI Initiative website. To delve deeper into the OpenAPI specification itself, the Swagger documentation is an excellent resource. You can also explore practical applications and tools like SwaggerHub for collaboration and versioning.

Forming a solid understanding of OpenAPI schemas through examples like these helps bridge the gap between tech-savvy developers and less technical stakeholders, ensuring smoother API lifecycle management and a better overall development experience.