{"id":44698371,"url":"https://github.com/ohdearapp/oh-dear-openapi-spec","last_synced_at":"2026-02-15T08:36:30.894Z","repository":{"id":315741298,"uuid":"1060329813","full_name":"ohdearapp/oh-dear-openapi-spec","owner":"ohdearapp","description":"An OpenAPI 3 spec for the Oh Dear! API","archived":false,"fork":false,"pushed_at":"2026-02-10T16:40:12.000Z","size":333,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-10T20:43:42.475Z","etag":null,"topics":["oas3","oh-dear","open-api-v3","openapi","openapi-specification","openapi3"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohdearapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"permafrost-dev","custom":"https://permafrost.dev/open-source"}},"created_at":"2025-09-19T18:21:06.000Z","updated_at":"2026-02-10T19:59:50.000Z","dependencies_parsed_at":"2025-09-20T13:07:03.675Z","dependency_job_id":"559c3b9a-e670-4390-9f05-f1cf99bfb32f","html_url":"https://github.com/ohdearapp/oh-dear-openapi-spec","commit_stats":null,"previous_names":["permafrost-dev/oh-dear-openapi-spec"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ohdearapp/oh-dear-openapi-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearapp%2Foh-dear-openapi-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearapp%2Foh-dear-openapi-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearapp%2Foh-dear-openapi-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearapp%2Foh-dear-openapi-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohdearapp","download_url":"https://codeload.github.com/ohdearapp/oh-dear-openapi-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearapp%2Foh-dear-openapi-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29473718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T06:58:05.414Z","status":"ssl_error","status_checked_at":"2026-02-15T06:58:05.085Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oas3","oh-dear","open-api-v3","openapi","openapi-specification","openapi3"],"created_at":"2026-02-15T08:36:30.187Z","updated_at":"2026-02-15T08:36:30.885Z","avatar_url":"https://github.com/ohdearapp.png","language":null,"funding_links":["https://github.com/sponsors/permafrost-dev","https://permafrost.dev/open-source"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/oh-dear-logo-rgb.png\" alt=\"Oh Dear! Logo\" width=\"200\"/\u003e\n  \u003cbr/\u003e\n    \u003cimg src=\"./assets/openapi-pantone.png\" alt=\"OpenAPI Logo\" width=\"200\"/\u003e\n    \u003cbr/\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/ohdearapp/oh-dear-openapi-spec?logo=opensourceinitiative\u0026logoColor=white\" alt=\"License: MIT\" /\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/ohdearapp/oh-dear-openapi-spec?logo=github\u0026logoColor=white\u0026nocache=1\" alt=\"Latest Version\" /\u003e\n    \u003cimg \n        src=\"https://img.shields.io/github/release-date/ohdearapp/oh-dear-openapi-spec?logo=github\u0026displayDate=published_at\u0026logoColor=white\u0026label=last+released\u0026color=%236BA539\" \n        alt=\"GitHub Last Release\" \n    /\u003e\n    \u003cimg src=\"https://qlty.sh/badges/b28124b6-e46f-429d-8abb-7426ba909401/maintainability.svg\" alt=\"Maintainability\" /\u003e\n\u003c/p\u003e\n\nThis project provides both [OpenAPI](./specs/oh-dear.openapi.yaml) and [Arazzo](./specs/oh-dear.arazzo.yaml) specifications for the excellent [Oh Dear! monitoring service](https://ohdear.app).\n\n## Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [About Oh Dear](#about-oh-dear)\n- [History](#history)\n- [Specifications](#specifications)\n    - [OpenAPI](#openapi)\n    - [Arazzo](#arazzo)\n- [Repository Structure](#repository-structure)\n- [Usage](#usage)\n    - [Generating Documentation](#generating-documentation)\n    - [Generating SDKs](#generating-sdks)\n- [Validation](#validation)\n- [Development](#development)\n- [Status](#status)\n- [Contributing](#contributing)\n- [Changelog](#changelog)\n- [Security Vulnerabilities](#security-vulnerabilities)\n- [Credits](#credits)\n- [License](#license)\n\n## About Oh Dear\n\n[Oh Dear!](https://ohdear.app) is an all-in-one monitoring tool for your websites. \nIt offers uptime monitoring, SSL certificate checking, broken link detection, scheduled task monitoring, and much more. \nThis project aims to provide comprehensive, community-driven API specifications to make integrations with Oh Dear! a breeze.\n\n## History\n\nThis project was originally created and maintained by [Patrick Organ](https://github.com/patinthehat) under the [permafrost-dev](https://github.com/permafrost-dev) organization. It has since been migrated to the [ohdearapp](https://github.com/ohdearapp) organization, where Oh Dear will manage and maintain it going forward. We gratefully acknowledge the original work done by permafrost-dev that made this project possible.\n\n## Specifications\n\n### OpenAPI\n\nThe OpenAPI specification follows the [v3.1.0 standard](https://spec.openapis.org/oas/v3.1.0). It provides a detailed, machine-readable description of the Oh Dear! API. This makes it easy to:\n\n- Generate client SDKs for various programming languages.\n- Create server stubs for testing and development.\n- Produce interactive API documentation.\n- Import into tools like Postman for easy API exploration.\n\nIt is particularly useful for building robust [third-party integrations](https://ohdear.app/docs/integrations/3rd-party-integrations-of-oh-dear) and [SDKs](https://ohdear.app/docs/integrations/the-oh-dear-php-sdk).\n\n### Arazzo\n\nThe Arazzo specification follows the [v1.0.1 standard](https://github.com/OAI/Arazzo-Specification/blob/main/versions/1.0.1.md) and \ndefines how the API works in real-world scenarios. It describes workflows that require one or more steps with request/response \nseries. A primary benefit is providing the ability to programmatically test the OpenAPI specification and ensure that API workflows \nbehave as expected.\n\n## Repository Structure\n\nA quick overview of the most relevant files and directories:\n\n```text\n├── specs/\n│   ├── oh-dear.openapi.yaml   # Primary OpenAPI 3.1.2 specification\n│   └── oh-dear.arazzo.yaml    # OpenAPI Arazzo 1.0.1 workflow specification\n├── config/\n│   ├── .markdownlint.yaml     # markdownlint configuration for linting Markdown files\n│   ├── .spectral.yaml         # Spectral configuration for linting the OpenAPI spec\n│   └── vacuum-ruleset.yaml    # Custom ruleset used for additional quality linting\n├── assets/                    # Logos and images used in the README/docs\n├── package.json               # Lint scripts and dependencies (Spectral \u0026 Redocly CLI)\n├── CHANGELOG.md               # Changelog for tracking notable changes\n├── LICENSE.md                 # MIT License\n└── README.md\n```\n\n- `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.\n- `config/.spectral.yaml` configures [Spectral](https://github.com/stoplightio/spectral) for linting the OpenAPI specification.\n- `config/.markdownlint.yaml` configures [markdownlint](https://github.com/igorshubovych/markdownlint-cli) for linting Markdown files.\n- `config/vacuum.yaml` is an extended quality ruleset (Vacuum) enforcing style, documentation completeness, schema rigor, and structural integrity on top of default linters.\n- `assets/` stores project branding and visual resources.\n\n\u003cimg src=\"./assets/chart-project-files.png\" alt=\"Project Structure\" width=\"100%\" style=\"align: center; width:100%;\"/\u003e\n\n## Usage\n\nTo use these specifications, you'll need Node.js and npm installed. First, clone the repository and install the dependencies:\n\n```bash\ngit clone https://github.com/ohdearapp/oh-dear-openapi-spec.git\ncd oh-dear-openapi-spec\nnpm install\n```\n\n### Generating Documentation\n\nYou can generate beautiful, interactive API documentation from the OpenAPI specification using tools like [Redocly](https://redocly.com/):\n\n```bash\nnpx @redocly/cli build-docs specs/oh-dear.openapi.yaml\n```\n\nThis will generate a `redoc-static.html` file in the root of the project.\n\n### Generating SDKs\n\nA wide range of tools can generate client SDKs from OpenAPI specifications. One popular option is the [OpenAPI Generator CLI](https://openapi-generator.tech/).\n\nFor example, to generate a TypeScript SDK:\n\n```bash\nnpx @openapitools/openapi-generator-cli generate \\\n  -i specs/oh-dear.openapi.yaml -g typescript-axios \\\n  -o ./generated-sdk/ts\n```\n\n## Validation\n\nThis project uses multiple layers of validation to ensure specification quality:\n\n1. **Spectral** (`@stoplight/spectral-cli`) – General OpenAPI best practice and style conformance.\n2. **Redocly CLI** (`@redocly/cli`) – Structural validation and bundling consistency.\n3. [**Vacuum**](https://github.com/daveshanley/vacuum) – An ultra-super-fast, lightweight OpenAPI linter and quality checking tool. \n4. Enhanced quality checks: description presence \u0026 duplication, schema typing, path ambiguity, enum uniqueness, security-related \n5. markdown hygiene, and naming conventions.\n\nRun all standard validations:\n\n```bash\nnpm run lint\n```\n\nRun individually:\n\n```bash\nnpm run lint:open-api   # Lints specs/oh-dear.openapi.yaml via Spectral\nnpm run lint:arazzo     # Lints specs/oh-dear.arazzo.yaml via Redocly CLI\n```\n\nOr lint the OpenAPI specification using individual npm scripts:\n\n```bash\nnpm run lint:open-api:spectral  # Lints specs/oh-dear.openapi.yaml via Spectral\nnpm run lint:open-api:vacuum    # Lints specs/oh-dear.openapi.yaml via Vacuum\nnpm run lint:open-api           # Lints using Spectral CLI only.\n```\n\n## Development\n\nThe OpenAPI specification file was created using [Stoplight Studio](https://stoplight.io/studio/), GPT-5, and manual \nediting in VSCode. The official Oh Dear! documentation and PHP SDK source code were treated as the source of truth.\n\nThe Arazzo specification was initially generated by `@redocly/cli` from the OpenAPI specification, then manually edited \nin VSCode to ensure accuracy and completeness.\n\n## Status\n\nThe specifications are a work in progress. The OpenAPI specification is approximately 95% complete, while the Arazzo specification\nis around 70% complete. Keep an eye on the [CHANGELOG](CHANGELOG.md) and the issue tracker for updates.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a pull request or create an issue for any bugs, suggestions, or questions you\nmay have. See the [issue tracker](https://github.com/ohdearapp/oh-dear-openapi-spec/issues) for a list of open items.\n\nWhen contributing changes to the specs:\n\n- Run `npm run lint` before opening a PR.\n- Keep descriptions meaningful—avoid duplication.\n- Favor reusable components where appropriate (consider refactoring repeated schema fragments).\n- If adding workflows, ensure Arazzo steps align with existing operationIds.\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Security Vulnerabilities\n\nPlease review our [security policy](https://github.com/ohdearapp/oh-dear-openapi-spec/security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Patrick Organ](https://github.com/patinthehat)\n- [Mattias Geniar](https://github.com/mattiasgeniar)\n- [All Contributors](https://github.com/ohdearapp/oh-dear-openapi-spec/graphs/contributors)\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohdearapp%2Foh-dear-openapi-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohdearapp%2Foh-dear-openapi-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohdearapp%2Foh-dear-openapi-spec/lists"}