📢 Open API Spec

📢 Open API Spec

📢 Open API Spec is a standardised specification format that defines HTTP APIs.

Open API Spec aims to provide language-based interfaces that are machine-readable, and human-friendly so that all necessary information over the available HTTP resources can be understood without necessarily accessing its source code, documents or network traffic inspections.

Hence, Open API Spec provides a standardised and structured format representing API's:

• endpoints (e.g. /members)
• operations (e.g. GET, POST, PUT, DELETE)
• request & response formats
• authentication methods
• others

Open API Spec explicitly sets an API contracts between API consumers and producers via JSON and YAML files.

🕋 Structure

The structure of Open API can be represented as below where it contains a skeleton script of a YML file describing the Open API.

Open API spec (YML skeleton)

An OpenAPI document can be written in JSON or YAML, and it will have the following structure:

# The Version of the OpenAPI Specification used (swagger for version 2)
openapi: "3.1.0"

# General information about the API
info: ...

# Paths and operations
paths:
  /books:
    get: ...

# Reusable components
components: ...

and for further details, remaining gaps can be filled like underneath:

Open API spec (YML)

openapi: 3.0.3
info:
  title: User Management API
  description: API for managing users, including creating, retrieving, updating, and deleting user resources.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging.api.example.com/v1
    description: Staging server
paths:
  /users:
    get:
      summary: Retrieve all users
      description: Fetch a list of all users in the system.
      operationId: getUsers
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a new user
      description: Add a new user to the system.
      operationId: createUser
      requestBody:
        description: User to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      description: Fetch details of a specific user by their ID.
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a user
      description: Update details of an existing user.
      operationId: updateUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: Updated user information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      summary: Delete a user
      description: Remove a user by their ID.
      operationId: deleteUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: User deleted successfully

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
        status:
          type: string
          enum: [active, inactive]
    UserCreate:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
    UserUpdate:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

🏭 Practices

Open API Spec in practices can be enabled via automating tools where Swagger, its originator, happens to be the most popular tool that implements Open API Spec.

Swagger eliminates a document writing task from a developer as it analyses the available APIs from its source code and represent it in the Open Api Spec. Hence, the developers can focus on developing a project than maintaining the API documents.

For its actual implementation please refer here

📚 References

Open API Initiative
Swagger
F-Lab
Postman