Publish a full OpenAPI spec for REST API v2 - #108
Conversation
172 paths / 270 operations generated from the live route index, the v2 controllers, and the docs coverage checklist; CustomGPT page now links the full spec as the canonical machine-readable description.
Batch update items now require the record id, global and controller batch create items share the single-route input schemas, and the global batch updates group is documented as non-functional (updates controller has no create_item).
Per-monitor active description no longer claims global scope; documented 400 responses on costs add/edit (no target) and per-site update (suspended site), only where the controllers really throw them.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Important Review skippedReview was skipped as selected files did not have any reviewable changes. 💤 Files selected but had no reviewable changes (1)
⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughThe PR adds a complete OpenAPI 3.1 reference for MainWP Dashboard REST API v2. It documents core and extension endpoints, reusable schemas, authentication, errors, queued jobs, and links to the specification from API documentation. ChangesREST API v2 reference
Estimated code review effort: 5 (Critical) | ~90+ minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
api-reference/openapi.yaml (2)
2872-2874: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd
itemsto the untyped arrays.
expected_statusdeclarestype: arraywith noitems. The same gap exists forsync_data(Lines 5065-5067, 5168-5170),mainwp_widgets(Lines 6232-6234),automatic_daily_update(Lines 6133-6135),trans_automatic_daily_update(Lines 6262-6264),mainwp_uptime_monitoring_up_status_codes(Lines 6523-6525), andpost_gallery_images(Lines 4259-4261).OpenAPI 3.1 accepts this, so the document stays valid. Code generators and try-it consoles then treat each field as an array of any type and show no usable example.
♻️ Proposed change for `expected_status`
expected_status: type: array + items: + type: integer description: Expected HTTP status codes.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api-reference/openapi.yaml` around lines 2872 - 2874, Update the array schemas for expected_status, sync_data, mainwp_widgets, automatic_daily_update, trans_automatic_daily_update, mainwp_uptime_monitoring_up_status_codes, and post_gallery_images to declare appropriate items schemas, preserving each field’s intended element type so generators and consoles can provide usable examples.
135-234: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winExtract the repeated request bodies into
components.requestBodies.
post,put, andpatchon this path carry three byte-identical copies of the same inline schema. The same triplication repeats on/clients/batch,/costs/batch,/sites/batch, and/tags/batch. A later edit to one method leaves the other two stale, and the published reference then shows two different contracts for one route.Define each body once under
components.requestBodiesand reference it from all three methods.♻️ Proposed refactor
requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - sites: - ... + $ref: '`#/components/requestBodies/GlobalBatchRequest`'Then add the shared definition under
components:components: requestBodies: GlobalBatchRequest: required: true content: application/json: schema: type: object properties: sites: {} # move the existing definition here unchanged🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api-reference/openapi.yaml` around lines 135 - 234, Extract the repeated inline batch request schema from the post, put, and patch operations into a shared components.requestBodies.GlobalBatchRequest definition, preserving the existing schema unchanged. Replace each operation’s requestBody with a reference to this shared request body, and apply the same deduplication to the corresponding batch endpoints for clients, costs, sites, and tags.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api-reference/openapi.yaml`:
- Around line 2869-2871: Update the descriptions for the `active` fields to say
“Enable or disable monitoring globally” instead of “Active or disable monitoring
globally” at this occurrence and every other listed occurrence, including the
entries near lines 2941, 4740, 4832, 4880, 6500, and 6569.
- Line 13039: Update all four x-requires-extension values in the OpenAPI
definition to use the consistent “MainWP Lighthouse” product name, replacing any
bare “Lighthouse” values while leaving unrelated extension values unchanged.
---
Nitpick comments:
In `@api-reference/openapi.yaml`:
- Around line 2872-2874: Update the array schemas for expected_status,
sync_data, mainwp_widgets, automatic_daily_update, trans_automatic_daily_update,
mainwp_uptime_monitoring_up_status_codes, and post_gallery_images to declare
appropriate items schemas, preserving each field’s intended element type so
generators and consoles can provide usable examples.
- Around line 135-234: Extract the repeated inline batch request schema from the
post, put, and patch operations into a shared
components.requestBodies.GlobalBatchRequest definition, preserving the existing
schema unchanged. Replace each operation’s requestBody with a reference to this
shared request body, and apply the same deduplication to the corresponding batch
endpoints for clients, costs, sites, and tags.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a434faf2-747e-4124-a9cd-064737a6d8db
📒 Files selected for processing (3)
advanced/api/customgpt-schema-for-mainwp-rest-api-v2.mdxapi-reference/openapi.yamlapi-reference/rest-api/overview.mdx
Fix the Enable/disable verb error in toggle descriptions, prefix the Lighthouse x-requires-extension values, and type the array fields whose element shape the controllers prove; sync_data and mainwp_widgets become objects because their validators reject JSON arrays outright.
|
@coderabbitai Dispositions for the four findings, fixes in 1a9dd20:
|
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
git show --stat --oneline 1a9dd20
git show --format=fuller --find-renames --find-copies -- api-reference/openapi.yaml 1a9dd20
printf '\n--- Matching documentation and generator references ---\n'
rg -n -i -C 2 'generated|generator|active or disable|MainWP Lighthouse|post_gallery_images|sync_data|mainwp_widgets|expected_status|automatic_daily_update|trans_automatic_daily_update|requestBodies' \
api-reference README.md .github 2>/dev/null || trueLength of output: 25204
One issue remains for 🐇🔎 ✏️ Learnings added
You are interacting with an AI system. |
An array payload degrades to the string "Array" in the sanitizer and can never validate; the route's own settings schema already declares string.
|
@coderabbitai expected_status is now declared |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
git show --format=fuller --find-renames --find-copies c565f33 -- api-reference/openapi.yaml
printf '\n--- Current expected_status declarations ---\n'
rg -n -A8 -B3 '^\s*expected_status:' api-reference/openapi.yaml
printf '\n--- Count and schema-shape checks ---\n'
python3 - <<'PY'
from pathlib import Path
import re
text = Path("api-reference/openapi.yaml").read_text()
blocks = list(re.finditer(r'(?ms)^(\s*)expected_status:\n(.*?)(?=^\1\S|\Z)', text))
print(f"expected_status blocks: {len(blocks)}")
for index, block in enumerate(blocks, 1):
body = block.group(0)
print(f"\nBlock {index}:")
print(" has type: string:", bool(re.search(r'(?m)^\s+type:\s*string\s*$', body)))
print(" has items:", bool(re.search(r'(?m)^\s+items:\s*$', body)))
PYLength of output: 6154
You are interacting with an AI system. |
A customer asked for a permalink to clean OpenAPI YAML their software can ingest
(Intercom, 2026-08-01). The closest thing we had was the CustomGPT schema page, which is
YAML inside an MDX fence and trimmed to about 30 operations to fit CustomGPT's cap. This
PR adds the real thing.
What changed
api-reference/openapi.yaml: complete OpenAPI 3.1.0 description of REST API v2.172 paths, 270 operations, 28 component schemas. Built from three sources: the live
/wp-json/mainwp/v2/route index of a testbed Dashboard, the v2 controllers inmainwp-6 (params, enums, response envelopes), and the 15 pages under
api-reference/rest-api/as the coverage checklist.info.versionis 6.1.3, theDashboard version the spec was written against.
api-reference/rest-api/overview.mdx: new OpenAPI Specification section with the rawGitHub permalink, plus a What You'll Learn bullet and a Related Resources entry, so
the file is discoverable from the page integrators read.
advanced/api/customgpt-schema-for-mainwp-rest-api-v2.mdx: the NOTE now says theCustomGPT schema is a trimmed subset and links the full spec.
Route count reconciliation
The live index reports 165 registered routes. WordPress registers separate regex
variants for numeric-id and domain forms of the same path, so those merge to 162
canonical paths; dropping the namespace root leaves 161. Four extension groups
documented in
extensions.mdx(SSL Monitor, Domain Monitor, Lighthouse, Pro Reports)were not installed on the testbed, adding 11 paths the index could not show. 161 + 11 =
172 spec paths. Extension-gated paths carry
x-requires-extension.What to look at
the record id and the global batch create schemas diverged from their single-route
counterparts; both are fixed with shared component schemas (
5af452a). The global/batchupdates group is documented as non-functional because the updates controllerhas no
create_item(); that is a product bug, reported separately, not a spec error.http_user,http_pass,uniqueid) are markedwriteOnly on purpose; the controller strips them from responses.
Verification
npx @redocly/cli lint: 0 errors, 0 warnings.mint broken-links: clean.MDX pages appears in the spec with its registered methods.
add, pages create.
clean). Review fixes landed as their own commits: batch schema corrections (
5af452a)and documented 400 responses plus a per-monitor description fix (
cdb9897).https://github.com/ghraw/mainwp/docs/main/api-reference/openapi.yamlparses in a validator. That URL only exists once this lands on main.
Out of scope
Wiring the spec into
docs.jsonso Mintlify generates reference pages. The 15hand-written endpoint pages are unchanged.
Summary by CodeRabbit
New Features
Documentation