Skip to main content

OpenAPI Document

Overview​

An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification. The speification is a machine-readable interface definition language for describing, producing, consuming and visualising web services.

Visualisation tools and libraries such as SwaggerUI and Scalar interpret OpenAPI documents in different ways. This means that a single OpenAPI document can output different visually distinct documentation, depending on the UI tool or library used.

The following details the basic OpenAPI structure, followed by an example using an Abair API endpoint.

Structure​

1. OpenAPI Version and Metadata​

openapi: '3.0.3'
info:
  title: Abair API
  version: '4.0.0'
  description: |
    Abair API Documentation for Endpoints

The beginning of the document.

openapi: Specifies OpenAPI version
info: Provides metadata such as title, API version and description.

2. Servers Section​

servers:
  - url: https://api.abair.ie
    description: Base URL
  - url: wss://stream.abair.ie
    description: Base WebSocket Handshake URL

Defines where the API Gateway is hosted. Multiple URLs can be defined for different protocols (HTTP vs WebSocket)

3. Tags Section​

tags:
  - name: Recognition
    description: Speech-to-text endpoints
  - name: Synthesis
    description: Text-to-speech endpoints
  - name: Stream
    description: Real-time streaming endpoints

Organises endpoints into logical groups for clarity in documentation and tooling.

4. Paths Section​

paths:
    /endpoint:
        method:
            tags: [...]
            summary: Short description
            description: Detailed explanation and URL
            parameters: [...]
            requestBody: {...}
            responses: {...}
    /endpoint2:
        {...}

Paths object contains all available API routes. Each path defines available HTTP methods such as GET, POST, DELETE etc.

This concludes the OpenAPI document.

Extra Notes​

Dynamic Path Parameters​

For dynamic paths such as:

/recognition/{transcript_id}

These are declared using in: path and marked as required: true

      parameters:
        - name: abair-api-key
          in: header
          required: true
          schema:
            type: string
            example: <yourApiKey>

        - name: transcript_id
          in: query
          required: true
          schema:
            type: string
            example: 'abc123'
          description: ID of the transcript

Including Examples​

Example payload and responses e.g, example: 'abc123' are displayed for user clarity in the documentation.

Inlcusion of examples is recommended.

Example​

Example Endpoint​

POST /Recongition

paths:
    /recognition:
        post:
            tags: [Recognition]
            summary: Generate transcript
            description: |
            Convert speech to text from media file or accessible URL.

                        POST: https://api.abair.ie/recognition

Specific endpoint URL is included in the description as a code snippet.

Parameters

parameters:
    - name: abair-api-key
        in: header
        required: true
        schema:
            type: string
            example: <yourApiKey>

Required is set to true, and lets the OpenAPI doc interpreter know that this parameter must be included in the 'send test request' section.

Request Body

requestBody:
    content:
        application/json:
            schema:
                type: object
                required:
                    - file
                properties:
                    file:
                        type: string
                        example: myAudio.mp3
                        description: File to be transcribed

Defines payload structure for POST/PUT requests.

Responses

responses:
    '201':
        description: Transcript submitted successfully
        content:
            application/json:
                schema:
                    type: object
                    properties:
                        transcript_id:
                            type: string
                            example: 'abc123'
                        status:
                            type: string
                            example: 'processing'

Every endpoint must specify possible HTTP responses.

Interpreter​

Scalar​

Scalar is an open-source library for interpreting and visualising OpenAPI specified YAML or JSON documents.

It provides modern quality-of-life improvements to API documentation, such as the ability to view example endpoint usage code in a multitude of coding languages.

Self hosting using Scalar is free, and possible using the Scalar API-Reference library, via a Content-Delivery-Network (CDN) link,

<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>

Aesthetic changes and preferences can be made within the settings of the output Scalar webpage, and can be forced onto the UI before deploying, such as light mode, dark mode, and other colourful themes.