Examples of OpenAPI Specifications

Understanding OpenAPI Specifications

OpenAPI Specifications (OAS) are essential for documenting RESTful APIs. They provide a standardized way for developers to describe the capabilities of an API, making it easier for both humans and machines to understand. Below are three diverse examples of OpenAPI specifications that illustrate various use cases and contexts.

Example 1: User Management API Specification

Context

This example outlines an API for managing user accounts, which includes functionalities such as creating, updating, and deleting user profiles. It’s particularly useful for applications requiring user authentication and management.

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Retrieve all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created successfully

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Notes

• This specification uses basic CRUD operations (Create, Read, Update, Delete) for user management.
• You can extend it by adding more endpoints for functionalities like password resets and role management.

Example 2: E-commerce Product API Specification

Context

This example illustrates an API for an e-commerce platform that manages product listings. It includes functionalities for getting product details, adding new products, and updating existing product information.

openapi: 3.0.0
info:
  title: E-commerce Product API
  version: 1.0.0
paths:
  /products:
    get:
      summary: Get all products
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

    post:
      summary: Add a new product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '201':
          description: Product added successfully

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
        category:
          type: string

Notes

• The specification allows for easy integration with front-end applications for displaying products.
• Consider adding parameters for filtering products by category or price range.

Example 3: Weather API Specification

Context

This API provides weather data for various locations. It enables users to retrieve current weather conditions and forecasts, making it highly useful for both mobile apps and web applications.

openapi: 3.0.0
info:
  title: Weather API
  version: 1.0.0
paths:
  /weather/current:
    get:
      summary: Get current weather
      parameters:

        - in: query
          name: city
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current weather data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Weather'

components:
  schemas:
    Weather:
      type: object
      properties:
        temperature:
          type: number
        condition:
          type: string
        humidity:
          type: number

Notes

• The Weather API can be enhanced with additional endpoints for historical weather data or severe weather alerts.
• Ensure to handle errors, such as invalid city names, in the response definition.

These examples of examples of OpenAPI specifications highlight various functionalities and contexts, providing a clear starting point for developers looking to document their APIs effectively.