This project provides both OpenAPI and Arazzo specifications for the excellent Oh Dear! monitoring service.

Table of Contents

• Table of Contents
• About Oh Dear
• Specifications
  • OpenAPI
  • Arazzo
• Repository Structure
• Usage
  • Generating Documentation
  • Generating SDKs
• Validation
• Development
• Status
• Contributing
• Changelog
• Security Vulnerabilities
• Credits
• License

About Oh Dear

Oh Dear! is an all-in-one monitoring tool for your websites. It offers uptime monitoring, SSL certificate checking, broken link detection, scheduled task monitoring, and much more. This project aims to provide comprehensive, community-driven API specifications to make integrations with Oh Dear! a breeze.

Specifications

OpenAPI

The OpenAPI specification follows the v3.1.0 standard. It provides a detailed, machine-readable description of the Oh Dear! API. This makes it easy to:

• Generate client SDKs for various programming languages.
• Create server stubs for testing and development.
• Produce interactive API documentation.
• Import into tools like Postman for easy API exploration.

It is particularly useful for building robust third-party integrations and SDKs.

Arazzo

The Arazzo specification follows the v1.0.1 standard and defines how the API works in real-world scenarios. It describes workflows that require one or more steps with request/response series. A primary benefit is providing the ability to programmatically test the OpenAPI specification and ensure that API workflows behave as expected.

Repository Structure

A quick overview of the most relevant files and directories:

├── specs/
│   ├── oh-dear.openapi.yaml   # Primary OpenAPI 3.1 specification
│   └── oh-dear.arazzo.yaml    # Arazzo 1.0.1 workflow specification
├── config/
│   ├── .spectral.yaml           # Spectral configuration for linting the OpenAPI spec
│   └── vacuum-ruleset.yaml    # Custom ruleset used for additional quality linting
├── assets/                    # Logos and images used in the README/docs
├── package.json               # Lint scripts and dependencies (Spectral & Redocly CLI)
└── README.md

• specs/ contains the source-of-truth API contract files. Any change here should ideally be validated via the lint commands and—where applicable—reflected in downstream SDKs or docs.
• config/.spectral.yaml configures Spectral for linting the OpenAPI specification.
• config/vacuum-ruleset.yaml is an extended quality ruleset (Vacuum) enforcing style, documentation completeness, schema rigor, and structural integrity on top of default linters.
• assets/ stores project branding and visual resources.

Usage

To use these specifications, you'll need Node.js and npm installed. First, clone the repository and install the dependencies:

git clone https://github.com/permafrost-dev/oh-dear-openapi-spec.git
cd oh-dear-openapi-spec
npm install

Generating Documentation

You can generate beautiful, interactive API documentation from the OpenAPI specification using tools like Redocly:

npx @redocly/cli build-docs specs/oh-dear.openapi.yaml

This will generate a redoc-static.html file in the root of the project.

Generating SDKs

A wide range of tools can generate client SDKs from OpenAPI specifications. One popular option is the OpenAPI Generator CLI.

For example, to generate a TypeScript SDK:

npx @openapitools/openapi-generator-cli generate \
  -i specs/oh-dear.openapi.yaml -g typescript-axios \
  -o ./generated-sdk/ts

Validation

This project uses multiple layers of validation to ensure specification quality:

1. Spectral (@stoplight/spectral-cli) – General OpenAPI best practice and style conformance.
2. Redocly CLI (@redocly/cli) – Structural validation and bundling consistency.
3. Vacuum – An ultra-super-fast, lightweight OpenAPI linter and quality checking tool. Enhanced quality checks: description presence & duplication, schema typing, path ambiguity, enum uniqueness, security-related markdown hygiene, and naming conventions.

Run all standard validations:

npm run lint

Run individually:

npm run lint:open-api   # Lints specs/oh-dear.openapi.yaml via Spectral
npm run lint:arazzo     # Lints specs/oh-dear.arazzo.yaml via Redocly CLI

Development

The OpenAPI specification file was created using Stoplight Studio, GPT-5, and manual editing in VSCode. The official Oh Dear! documentation and PHP SDK source code were treated as the source of truth.

The Arazzo specification was initially generated by @redocly/cli from the OpenAPI specification, then manually edited in VSCode to ensure accuracy and completeness.

Status

The specifications are a work in progress. The OpenAPI specification is approximately 95% complete, while the Arazzo specification is around 70% complete. Keep an eye on the changelog and the issue tracker for updates.

Contributing

Contributions are welcome! Please feel free to submit a pull request or create an issue for any bugs, suggestions, or questions you may have. See the issue tracker for a list of open items.

When contributing changes to the specs:

• Run npm run lint before opening a PR.
• Keep descriptions meaningful—avoid duplication.
• Favor reusable components where appropriate (consider refactoring repeated schema fragments).
• If adding workflows, ensure Arazzo steps align with existing operationIds.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Patrick Organ
• All Contributors

License

This project is licensed under the MIT License.