[vmdef]

Replaces the handwritten Moodle Marketplace API page with a reference generated from the API's OpenAPI specification, so the documentation can no longer drift from the API.

The reference is rendered with docusaurus-plugin-openapi-docs and appears in Community → Plugin contribution → Moodle Marketplace API, in the same sidebar slot as the old page. All wording lives in the spec, on the Marketplace side; devdocs only makes the spec's root-relative links absolute.

How it works:

Marketplace  /api/docs.jsonopenapi
   |  daily workflow: fetch, validate, open a PR when the spec changed
   v
data/marketplace/openapi.json   committed snapshot
   |  yarn build (= yarn openapi + docusaurus build), no network needed
   v
general/community/plugincontribution/marketplace-api/   generated pages
   |  DocItem wrapper: API pages -> ApiItem (React.lazy), other pages unchanged
   v
Community > Plugin contribution > Moodle Marketplace API

Specification. The Marketplace publishes its OpenAPI document at /api/docs.jsonopenapi.

Snapshot. A copy of the specification is committed in devdocs (data/marketplace/openapi.json). A daily GitHub Actions workflow downloads it (30 s timeout), checks that it is an OpenAPI 3 document, verifies that it can still generate the reference, and opens a pull request only when it changes. The build never depends on the Marketplace being reachable, and every specification change is reviewed.

Generation. yarn build runs yarn openapi: a script sets the public server URL and makes the root-relative links in the descriptions absolute, then the plugin generates the pages into general/community/plugincontribution/marketplace-api/ (git-ignored, except category.yml). They appear in Community > Plugin contribution > Moodle Marketplace API, the sidebar slot of the old hand-written page, which is removed.

Content ownership. The reference wording lives in the specification on the Marketplace side. devdocs carries no hand-written content for it.

Rendering. API pages use the theme's ApiItem component through a DocItem wrapper that loads it with React.lazy, so its code (about 5.7 MB uncompressed, 1.8 MB gzipped) is a separate chunk downloaded only by API pages. Every other page renders exactly as before.

Scope. The reference is read-only: sending requests from the page is disabled. Code samples are limited to PHP (Guzzle), cURL, JavaScript, NodeJS and Python (http.client).

[netlify]

✅ Deploy Preview for moodledevdocs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	832e5ce
🔍 Latest deploy log	https://app.netlify.com/projects/moodledevdocs/deploys/6ae1cef0f24f161eb6ec1234
😎 Deploy Preview	https://deploy-preview-1702--moodledevdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[andrewnicols]

Pinging @vmdef , is this still current?

[vmdef]

Yes, it is. We aim to compare two plugins that generate documentation from an OpenAPI specification (MKPL-1735). Our plan is to create drafts for each plugin so they are deployed to Nelify, and then select the one that best fits our needs.
I expected to finish it by now, but I've been postponing it due to other priorities. I hope to complete it by this week or early next week.

[Copilot]

🟡 Changes recommended

Development startup, automation isolation, URL compatibility, and read-only behavior need corrections before approval.

5 open issues

• Use a dedicated branch for the metadata update workflow · New
• Remove Swagger-specific instructions from the Marketplace introduction · New
• Prevent implicit API submission in the read-only reference · New
• Add a redirect from the removed Marketplace API URL · New
• Generate API pages before running the local preview · New

What changed in this PR

Replaces the handwritten Marketplace API guide with an OpenAPI-generated reference in the existing Community documentation.

Changes:

• Adds a committed specification, preparation script, and daily update workflow.
• Integrates OpenAPI generation into builds and lazy-loads API rendering.
• Updates navigation and excludes generated pages from Git and Markdown linting.

File	Description
yarn.lock	Locks OpenAPI dependencies.
src/​theme/​DocItem/​index.js	Lazy-loads the API renderer.
scripts/​marketplace-openapi.mjs	Fetches and prepares the specification.
package.json	Adds generation commands and dependencies.
general/​community/​plugincontribution/​pluginsdirectory/​api.md	Links to the generated introduction.
general/​community/​plugincontribution/​moodlemarketplaceapi.md	Removes the handwritten guide.
general/​community/​plugincontribution/​marketplace-api/​_category_.yml	Defines the reference sidebar entry.
docusaurus.config.js	Configures generation, theme, and code samples.
data/​marketplace/​openapi.json	Stores the API specification snapshot.
.markdownlint-cli2.cjs	Excludes generated documentation.
.gitignore	Ignores prepared specifications and generated pages.
.github/​workflows/​update-marketplace-api.yml	Automates specification update PRs.

_{Review effort: Balanced}

[andrewnicols]

Just to confirm, will we be able to have multiple openapi.json configs for different parts of Moodle?

[vmdef]

Though I haven't tested it, the plugin's config accepts any number of specs, each with its own specPath, outputDir, and sidebar options, and yarn openapi already generates them all.

Adding a new API mostly means adding a new config entry and likely its own fetch/prepare step.

Shared by every API:

• the code sample language tabs (docusaurus.config.js)
• the read-only "Send" blocking (src/theme/ApiExplorer/Request/index.js)

If any API needs something different, it would require some changes.

I have doubts about versioning. Right now it writes into the unversioned general docs. Perhaps different versions could require APIs tied to Moodle releases to have a second plugin instance that targets the versioned docs instance.

For now, we use general to keep the documentation in the current location, but APIs could have a specific instance/path.