Repository navigation
Conversation
✅ Deploy Preview for moodledevdocs ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Member
|
Pinging @vmdef , is this still current? |
Contributor
Author
|
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. |
vmdef
changed the title
vmdef
changed the title
vmdef
force-pushed
the
add-marketplace-api
branch
5 times, most recently
from
October 20, 2026 15:50
fcdafde to
cda8be9
Compare
vmdef
marked this pull request as ready for review
October 20, 2026 17:05
vmdef
marked this pull request as draft
October 20, 2026 17:06
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Development startup, automation isolation, URL compatibility, and read-only behavior need corrections before approval.
5 open issues
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
|
|
||
| - name: Create Pull Request | ||
| uses: peter-evans/create-pull-request@38e0b6e68b4c852a5500a94740f0e535e0d7ba54 # v4.2.4 | ||
| with: |
| "openapi": "3.1.0", | ||
| "info": { | ||
| "title": "Moodle Marketplace API", | ||
| "description": "Programmatic access to the Moodle Marketplace: browse the plugin catalogue and submit new\nversions of the plugins you maintain.\n\n## Authenticating\n\nEvery request needs a bearer token. Create one from your account's\n[security settings](/account/security), under **API tokens**.\n\n> The raw token is shown **once**, in a dialog that stops offering it after 60 seconds. It is\n> stored hashed and cannot be retrieved later, only replaced. You may hold up to **10 active\n> tokens**; past that, revoke one before creating another.\n\nSend it on every call:\n\n```\nAuthorization: Bearer YOUR_TOKEN\n```\n\nTo try the endpoints from this page, click **Authorize** above and paste the raw token — with\nno `Bearer ` prefix, Swagger adds it for you.\n\nA missing, malformed, expired or revoked token gives `401`. Tokens act as you: an endpoint\nreturns exactly what your user account is allowed to see or do.\n\n## Responses\n\nEverything is plain JSON (`application/json`). Collections are **bare JSON arrays**.\n\nThere is **no pagination**: a collection returns everything you are allowed to see in one\nresponse.\n\n## Errors\n\nFailures answer with the appropriate status code and an\n[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` body. There is no\nsuccess flag to check in the body — the status code is the answer.\n\n```json\n{\n \"status\": 422,\n \"title\": \"An error occurred\",\n \"detail\": \"file: The archive does not contain a valid version.php.\",\n \"violations\": [\n { \"propertyPath\": \"file\", \"message\": \"The archive does not contain a valid version.php.\" }\n ]\n}\n```\n\n| Status | Meaning |\n| --- | --- |\n| `400` Bad request | The request itself was malformed. |\n| `401` Unauthorized | No token, or the token is not valid. |\n| `403` Forbidden | Authenticated, but not allowed to see or change this resource. |\n| `404` Not found | No such resource. |\n| `406` Not acceptable | You asked for a media type this API does not serve. |\n| `409` Conflict | The resource is in a state that does not allow this operation. |\n| `422` Unprocessable Content | The request was well formed but its contents were rejected. See `violations`. |\n\n`violations` lists one entry per problem, each with the offending `propertyPath` and a\nhuman-readable `message`. Show those to the user; do not parse the messages.\n\n## Stability\n\nThis is version 1 of a young API and it will grow. **New fields may be added to any response\nwithout notice**, so parse defensively and ignore what you do not recognise. Fields will not be\nremoved or change meaning within `v1`.", |
| specPath: '.openapi/marketplace.json', | ||
| outputDir: 'general/community/plugincontribution/marketplace-api', | ||
| // Disables the "Try it" request sender: the reference is read-only. | ||
| hideSendButton: true, |
| :::warning | ||
|
|
||
| This page describes the Plugins Directory API, not [Moodle Marketplace APIs](general/community/plugincontribution/moodlemarketplaceapi.md). | ||
| This page describes the Plugins Directory API, not the [Moodle Marketplace API](../marketplace-api/moodle-marketplace-api). |
| @@ -5,13 +5,17 @@ | |||
| "scripts": { | |||
| "docusaurus": "docusaurus", | |||
| "start": "docusaurus start", | |||
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
vmdef
force-pushed
the
add-marketplace-api
branch
from
October 20, 2026 17:57
cda8be9 to
7b74c93
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-docsand 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:
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 buildrunsyarn 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).