Search: Build OpenAPI Definition using JavaScript

Copies the existing structure for now for simplicity and easy understanding

The openapi.json file can be validated to be semantically the same (e.g. with a tool like https://jsondiff.com)

Continue to use `$ref`s to `#/components` where feasible, to reduce the size of the OAD and increase readability

Bug: T379912
Change-Id: I8b2be98df2d6085d66e8627f19f63d51463f1020

Author: outdooracorn

repo/domains/search/.eslintrc.js

@@ -17,11 +17,13 @@ module.exports = {
 		"max-len": [ "warn", { code: 130 } ],
 		"no-implicit-coercion": [ "error", { disallowTemplateShorthand: true } ],
 		"no-console": "error",
-		"template-curly-spacing": 'off',
+		"template-curly-spacing": "off",
 	},
 	overrides: [
 		{
 			files: [ "*.json" ],
+			parser: "eslint-plugin-json-es",
+			extends: "plugin:eslint-plugin-json-es/recommended",
 			rules: {
 				"max-len": "off",
 			}

repo/domains/search/specs/.eslintrc.js

@@ -0,0 +1,17 @@
+'use strict';
+
+module.exports = {
+	"rules": { },
+	"overrides": [
+		{
+			"files": [ "*.js" ],
+			"rules": {
+				"brace-style": [ "warn", "1tbs", { "allowSingleLine": true } ],
+				"semi": [ "error", "always", { "omitLastInOneLineBlock": true } ],
+				// disable for now - easier to switch from JSON to JS if we aren't fussy about quotes
+				"quotes": "off",
+				"quote-props": "off",
+			}
+		},
+	]
+};

repo/domains/search/specs/global/parameters.json renamed to repo/domains/search/specs/global/parameters.js

@@ -1,4 +1,6 @@
-{
+'use strict';
+
+module.exports = {
 	"SearchQuery": {
 		"in": "query",
 		"name": "q",
@@ -42,4 +44,4 @@
 		},
 		"example": 4
 	}
-}
+};

repo/domains/search/specs/global/responses.json renamed to repo/domains/search/specs/global/responses.js

@@ -1,4 +1,8 @@
-{
+'use strict';
+
+const schemaParts = require( './schema-parts' );
+
+module.exports = {
 	"BadRequest": {
 		"description": "The request cannot be processed",
 		"content": {
@@ -36,7 +40,7 @@
 		"description": "A list of search results",
 		"content": {
 			"application/json": {
-				"schema": { "$ref": "./schema-parts.json#/SearchItemResultList" },
+				"schema": schemaParts.SearchItemResultList,
 				"example": {
 					"results": [
 						{
@@ -60,7 +64,7 @@
 		"description": "A list of search results",
 		"content": {
 			"application/json": {
-				"schema": { "$ref": "./schema-parts.json#/SearchPropertyResultList" },
+				"schema": schemaParts.SearchPropertyResultList,
 				"example": {
 					"results": [
 						{
@@ -80,4 +84,4 @@
 			}
 		}
 	}
-}
+};

repo/domains/search/specs/global/schema-parts.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const DisplayLabel = {
+	"type": [ "object", "null" ],
+	"properties": {
+		"language": { "type": "string" },
+		"value": { "type": "string" }
+	},
+	"additionalProperties": false,
+	"required": [ "language", "value" ],
+};
+
+const Description = {
+	"type": [ "object", "null" ],
+	"properties": {
+		"language": { "type": "string" },
+		"value": { "type": "string" }
+	},
+	"additionalProperties": false,
+	"required": [ "language", "value" ],
+};
+
+const Match = {
+	"type": "object",
+	"properties": {
+		"type": { "type": "string" },
+		"language": { "type": "string" },
+		"text": { "type": "string" }
+	},
+	"additionalProperties": false,
+	"required": [ "type", "text" ],
+};
+
+const SearchItemResult = {
+	"type": "object",
+	"properties": {
+		"id": {
+			"type": "string",
+			"pattern": "^Q[1-9]\\d{0,9}$"
+		},
+		"display-label": DisplayLabel,
+		"description": Description,
+		"match": Match
+	},
+	"additionalProperties": false,
+	"required": [ "id", "display-label", "description", "match" ],
+};
+
+const SearchPropertyResult = {
+	"type": "object",
+	"properties": {
+		"id": {
+			"type": "string",
+			"pattern": "^P[1-9]\\d{0,9}$"
+		},
+		"display-label": DisplayLabel,
+		"description": Description,
+		"match": Match
+	},
+	"additionalProperties": false,
+	"required": [ "id", "display-label", "description", "match" ],
+};
+
+const SearchItemResultList = {
+	"type": "object",
+	"properties": {
+		"results": {
+			"type": "array",
+			"items": SearchItemResult,
+		}
+	},
+	"additionalProperties": false,
+	"required": [ "results" ],
+};
+
+const SearchPropertyResultList = {
+	"type": "object",
+	"properties": {
+		"results": {
+			"type": "array",
+			"items": SearchPropertyResult,
+		}
+	},
+	"additionalProperties": false,
+	"required": [ "results" ],
+};
+
+module.exports = {
+	SearchItemResultList,
+	SearchPropertyResultList,
+};

repo/domains/search/specs/global/schema-parts.json

@@ -0,0 +1,76 @@
+'use strict';
+
+const parameters = require( './global/parameters' );
+
+const openapi = {
+	"openapi": "3.1.0",
+	"info": {
+		"title": "Wikibase Search Domain REST API",
+		"version": "0.1",
+		"description": "OpenAPI fragment of the Wikibase Search domain REST API"
+	},
+	"tags": [
+		{
+			"name": "item search",
+			"description": "Simple item search"
+		},
+		{
+			"name": "property search",
+			"description": "Simple property search"
+		}
+	],
+	"paths": {
+		"/v0/search/items": {
+			"get": {
+				"operationId": "simpleItemSearch",
+				"tags": [ "item search" ],
+				"summary": "Simple Item search by label and aliases",
+				"parameters": [
+					{
+						...parameters.SearchQuery,
+						"example": "potato"
+					},
+					{ "$ref": "#/components/parameters/SearchLanguage" },
+					{ "$ref": "#/components/parameters/Limit" },
+					{ "$ref": "#/components/parameters/Offset" },
+				],
+				"responses": {
+					"200": { "$ref": "#/components/responses/SearchItemSuccess" },
+					"400": { "$ref": "#/components/responses/BadRequest" }
+				}
+			}
+		},
+		"/v0/search/properties": {
+			"get": {
+				"operationId": "simplePropertySearch",
+				"tags": [ "property search" ],
+				"summary": "Simple Property search by label and aliases",
+				"parameters": [
+					{
+						...parameters.SearchQuery,
+						"example": "taxon"
+					},
+					{ "$ref": "#/components/parameters/SearchLanguage" },
+					{ "$ref": "#/components/parameters/Limit" },
+					{ "$ref": "#/components/parameters/Offset" },
+				],
+				"responses": {
+					"200": { "$ref": "#/components/responses/SearchPropertySuccess" },
+					"400": { "$ref": "#/components/responses/BadRequest" }
+				}
+			}
+		}
+	},
+	"components": {
+		"parameters": require( './global/parameters' ),
+		"responses": require( './global/responses' ),
+	},
+};
+
+// export the definition for use in other modules (useful in mocha tests and helpers, for example)
+module.exports = { openapi };
+
+if ( require.main === module ) {
+	// if executed directly, print the definition
+	console.log( JSON.stringify( openapi, null, 2 ) ); // eslint-disable-line no-console
+}

repo/domains/search/specs/index.fragment.js

@@ -5,3 +5,7 @@ specs/openapi-joined.json:
     - '#/paths/~1v1~1openapi.json/get/responses'
     - '#/paths/~1v1~1property-data-types/get/responses'
     - '#/paths/~1v0~1search~1items/get/responses'
+
+  # temporarily ignore
+  no-unused-components:
+    - '#/components/parameters/SearchQuery'