REST: Introduce discovery endpoint

The discovery endpoint provides basic information about accessing the
wiki's APIs, as well as a directory of available modules.

Bug: T365753
Change-Id: I161aa68566da91867b650e13c8aadc87cd0c428c

2 files changed, 88 insertions, 4 deletions

diff --git a/docs/rest/discovery-1.0.json b/docs/rest/discovery-1.0.json
new file mode 100644
index 000000000000..3afc744c5621
--- /dev/null
+++ b/docs/rest/discovery-1.0.json
@@ -0,0 +1,81 @@
+{
+	"$schema": "http://json-schema.org/draft-06/schema#",
+	"$id": "https://www.mediawiki.org/schema/discovery-1.0",
+	"title": "MediaWiki REST API discovery document",
+	"description": "Discovery documents provide all information needed to locate and access REST APIs on a given wiki.",
+	"type": "object",
+	"required": [ "info", "servers", "modules" ],
+	"properties": {
+		"mw-discovery": {
+			"description": "The version of the MediaWiki discovery schema used by the discovery document.",
+			"type": "string"
+		},
+		"info": {
+			"$ref": "#/definitions/Info"
+		},
+		"servers": {
+			"description": "A list of servers that can be used to access the APIs.",
+			"type": "array",
+			"minItems": 1,
+			"item": { "$ref": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Server" }
+		},
+		"modules": {
+			"description": "Information about the API modules available for interacting with the wiki. Depends on the extensions installed on the wiki, and may further vary with the wiki's version and configuration.",
+			"type": "object",
+			"minProperties": 1,
+			"additionalProperties": { "$ref": "#/definitions/Module" }
+		}
+	},
+	"definitions": {
+		"Info": {
+			"description": "Information about the wiki site that offers the API",
+			"type": "object",
+			"required": [
+				"title",
+				"mediawiki"
+			],
+			"properties": {
+				"title": {
+					"description": "The name of the wiki",
+					"type": "string"
+				},
+				"license": {
+					"$ref": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/License"
+				},
+				"contact": {
+					"$ref": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Contact"
+				},
+				"mediawiki": {
+					"description": "The version of the MediaWiki software serving the document",
+					"type": "string"
+				}
+			}
+		},
+		"Module": {
+			"title": "REST API Module",
+			"description": "Information about a given REST module available of the wiki. Corresponds to the https://www.mediawiki.org/schema/mwapi-1.0 schema.",
+			"type": "object",
+			"required": [
+				"info",
+				"base",
+				"spec"
+			],
+			"properties": {
+				"info": {
+					"$ref": "#/definitions/ModuleInfo"
+				},
+				"base": {
+					"description": "The base path of the module, to be appended to the server URL. This may or may not be a functioning endpoint, as defined by the module's specification.",
+					"type": "string"
+				},
+				"spec": {
+					"description": "URL of the module's OpenAPI specification. The version of OpenAPI used may vary.",
+					"type": "string"
+				}
+			}
+		},
+		"ModuleInfo": {
+			"$ref": "https://www.mediawiki.org/schema/mwapi-1.0#/definitions/Info"
+		}
+	}
+}
diff --git a/docs/rest/mwapi-1.0.json b/docs/rest/mwapi-1.0.json
index 7e4f9d41a4d4..875964eaaf2b 100644
--- a/docs/rest/mwapi-1.0.json
+++ b/docs/rest/mwapi-1.0.json
@@ -15,10 +15,7 @@
 			"type": "string"
 		},
 		"info": {
-			"allOf": [
-				{ "$ref": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Info" },
-				{ "$ref": "#/definitions/ExtraInfo" }
-			]
+			"$ref": "#/definitions/Info"
 		},
 		"paths": {
 			"description": "Information about the API routes available for interacting with the wiki.",
@@ -28,6 +25,12 @@
 		}
 	},
 	"definitions": {
+		"Info": {
+			"allOf": [
+				{ "$ref": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Info" },
+				{ "$ref": "#/definitions/ExtraInfo" }
+			]
+		},
 		"ExtraInfo": {
 			"type": "object"
 		},