diff --git a/package.json b/package.json index 4f2c3b3ed..551a052da 100644 --- a/package.json +++ b/package.json @@ -51,16 +51,17 @@ "ajv": "^6.10.0", "bunyan": "^1.8.12", "coveralls": "^3.0.3", + "eslint": "^5.16.0", "eslint-config-wikimedia": "^0.11.0", "eslint-plugin-jsdoc": "^4.7.0", "eslint-plugin-json": "^1.4.0", - "eslint": "^5.16.0", "js-yaml": "^3.13.0", "mocha": "^6.0.2", "mocha-lcov-reporter": "^1.3.0", "mocha.parallel": "^0.15.6", "nock": "^10.0.6", "nyc": "^13.3.0", + "openapi-schema-validator": "^3.0.3", "preq": "^0.5.7", "restbase-mod-table-sqlite": "^1.1.2" }, diff --git a/projects/wmf_wiktionary.yaml b/projects/wmf_wiktionary.yaml index 6306375f2..08020f8dc 100644 --- a/projects/wmf_wiktionary.yaml +++ b/projects/wmf_wiktionary.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 paths: /{api:v1}: &default_project_paths_v1 x-modules: diff --git a/sys/key_rev_value.yaml b/sys/key_rev_value.yaml index a22cff16c..7055e3ad1 100644 --- a/sys/key_rev_value.yaml +++ b/sys/key_rev_value.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 info: version: '1.0.0' title: RESTBase key-rev-value module diff --git a/sys/key_value.yaml b/sys/key_value.yaml index 734376fea..44eac1687 100644 --- a/sys/key_value.yaml +++ b/sys/key_value.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 info: version: '1.0.0' title: RESTBase key-value module diff --git a/sys/multi_content_bucket.yaml b/sys/multi_content_bucket.yaml index 76eaf164f..dd255327c 100644 --- a/sys/multi_content_bucket.yaml +++ b/sys/multi_content_bucket.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 info: version: '1.0.0' title: RESTBase multi-content-bucket module diff --git a/sys/page_revisions.yaml b/sys/page_revisions.yaml index b65f0f5da..061653fb1 100644 --- a/sys/page_revisions.yaml +++ b/sys/page_revisions.yaml @@ -7,7 +7,8 @@ paths: - name: page in: query description: The next page token - type: string + schema: + type: string required: false /page/{title}: &page_title @@ -23,7 +24,8 @@ paths: - name: page in: query description: The next page token - type: string + schema: + type: string required: false /page/{title}/{revision}: diff --git a/sys/parsoid.yaml b/sys/parsoid.yaml index e4e6356a5..46eab7551 100644 --- a/sys/parsoid.yaml +++ b/sys/parsoid.yaml @@ -1,4 +1,4 @@ -swagger: 2.0 +openapi: 3.0.1 info: version: 0.1.0 title: Internal Parsoid content API diff --git a/sys/post_data.yaml b/sys/post_data.yaml index ec9335bb1..038ab648b 100644 --- a/sys/post_data.yaml +++ b/sys/post_data.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 info: version: '1.0.0' title: RESTBase post data storage module diff --git a/test/features/pagecontent/pagecontent.js b/test/features/pagecontent/pagecontent.js index 5dcad76a5..c8dda4b7a 100644 --- a/test/features/pagecontent/pagecontent.js +++ b/test/features/pagecontent/pagecontent.js @@ -275,7 +275,7 @@ describe('item requests', function() { .then((res) => { assert.deepEqual(res.status, 200); assert.contentType(res, 'application/json'); - assert.deepEqual(res.body.swagger, '2.0'); + assert.deepEqual(res.body.openapi, '3.0.1'); }); }); diff --git a/test/features/schema_tests.js b/test/features/schema_tests.js index 4f06c416d..02f4840d0 100644 --- a/test/features/schema_tests.js +++ b/test/features/schema_tests.js @@ -8,6 +8,8 @@ const assert = require('../utils/assert.js'); const Server = require('../utils/server.js'); const preq = require('preq'); const Ajv = require('ajv'); +const OpenAPISchemaValidator = require('openapi-schema-validator').default; +const validator = new OpenAPISchemaValidator({ version: 3 }); parallel('Responses should conform to the provided JSON schema of the response', () => { const ajv = new Ajv({}); @@ -26,8 +28,8 @@ parallel('Responses should conform to the provided JSON schema of the response', before(() => server.start() .then(() => preq.get({uri: `${server.config.baseURL()}/?spec`})) .then((res) => { - Object.keys(res.body.definitions).forEach((defName) => { - ajv.addSchema(res.body.definitions[defName], `#/definitions/${defName}`); + Object.keys(res.body.components.schemas).forEach((defName) => { + ajv.addSchema(res.body.components.schemas[defName], `#/components/schemas/${defName}`); }); })); after(() => server.stop()); @@ -35,19 +37,14 @@ parallel('Responses should conform to the provided JSON schema of the response', it('should expose valid OpenAPI spec', () => { return preq.get({ uri: `${server.config.baseURL()}/?spec` }) .then((res) => { - return preq.post({uri: `http://online.swagger.io/validator/debug`, - body: JSON.stringify(res.body)}) - .then((res) => { - // if valid will return an empty object: {} - assert.deepEqual({}, res.body, 'Spec must have no validation errors'); - }) + assert.deepEqual({errors: []}, validator.validate(res.body), 'Spec must have no validation errors'); }); }); it('/feed/featured should conform schema', () => { return preq.get({ uri: `${server.config.baseURL()}/feed/featured/${getToday()}` }) .then((res) => { - if (!ajv.validate('#/definitions/feed', res.body)) { + if (!ajv.validate('#/components/schemas/feed', res.body)) { throw new assert.AssertionError({ message: ajv.errorsText() }); @@ -58,7 +55,7 @@ parallel('Responses should conform to the provided JSON schema of the response', it('/feed/featured should conform schema, ruwiki', () => { return preq.get({ uri: `${server.config.baseURL('ru.wikipedia.org')}/feed/featured/${getToday()}` }) .then((res) => { - if (!ajv.validate('#/definitions/feed', res.body)) { + if (!ajv.validate('#/components/schemas/feed', res.body)) { throw new assert.AssertionError({ message: ajv.errorsText() }); @@ -70,7 +67,7 @@ parallel('Responses should conform to the provided JSON schema of the response', it('/page/summary/{title} should conform schema', () => { return preq.get({ uri: `${server.config.baseURL()}/page/summary/Tank` }) .then((res) => { - if (!ajv.validate('#/definitions/summary', res.body)) { + if (!ajv.validate('#/components/schemas/summary', res.body)) { throw new assert.AssertionError({ message: ajv.errorsText() }); @@ -81,7 +78,7 @@ parallel('Responses should conform to the provided JSON schema of the response', it('/feed/announcements should conform schema', () => { return preq.get({ uri: `${server.config.baseURL()}/feed/announcements` }) .then((res) => { - if (!ajv.validate('#/definitions/announcementsResponse', res.body)) { + if (!ajv.validate('#/components/schemas/announcementsResponse', res.body)) { throw new assert.AssertionError({ message: ajv.errorsText() }); @@ -92,7 +89,7 @@ parallel('Responses should conform to the provided JSON schema of the response', it('/feed/onthisday should conform schema', () => { return preq.get({ uri: `${server.config.baseURL()}/feed/onthisday/all/01/03` }) .then((res) => { - if (!ajv.validate('#/definitions/onthisdayResponse', res.body)) { + if (!ajv.validate('#/components/schemas/onthisdayResponse', res.body)) { throw new assert.AssertionError({ message: ajv.errorsText() }); @@ -104,7 +101,7 @@ parallel('Responses should conform to the provided JSON schema of the response', it('/page/related should conform schema', () => { return preq.get({ uri: `${server.config.bucketURL()}/related/Tank` }) .then((res) => { - if (!ajv.validate('#/definitions/related', res.body)) { + if (!ajv.validate('#/components/schemas/related', res.body)) { throw new assert.AssertionError({ message: ajv.errorsText() }); diff --git a/test/test_module.yaml b/test/test_module.yaml index 8b8780dcb..e363696d5 100644 --- a/test/test_module.yaml +++ b/test/test_module.yaml @@ -1,6 +1,6 @@ # Simple test spec -swagger: 2.0 +openapi: 3.0.1 paths: /{api:v1}: x-modules: diff --git a/v1/announcements.yaml b/v1/announcements.yaml index ca85afbdd..abbd3effd 100644 --- a/v1/announcements.yaml +++ b/v1/announcements.yaml @@ -9,14 +9,13 @@ paths: Gets announcements for display in the official Wikipedia iOS and Android apps. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Announcements/0.2.0" - - application/problem+json responses: - '200': + 200: description: Announcements for the given Wiki - schema: - $ref: '#/definitions/announcementsResponse' + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Announcements/0.2.0": + schema: + $ref: '#/components/schemas/announcementsResponse' x-request-handler: - get_announcements_from_mcs: request: @@ -25,7 +24,8 @@ paths: gzip: false response: status: '{{get_announcements_from_mcs.status}}' - headers: '{{merge(get_announcements_from_mcs.headers, { "cache-control": options.announcement_cache_control})}}' + headers: '{{merge(get_announcements_from_mcs.headers, { "cache-control": + options.announcement_cache_control})}}' body: '{{get_announcements_from_mcs.body}}' x-monitor: true x-amples: @@ -37,76 +37,76 @@ paths: status: 200 headers: content-type: application/json +components: + schemas: + action: + type: object + properties: + title: + type: string + description: The title to display on the button that performs the action + url: + type: string + description: The URL to navigate to when the button is pressed + required: + - title + - url -definitions: - action: - type: object - properties: - title: - type: string - description: The title to display on the button that performs the action - url: - type: string - description: The URL to navigate to when the button is pressed - required: - - title - - url - - announcement: - type: object - properties: - id: - type: string - description: Unique ID of the announcement - type: - type: string - description: The type of announcement. Possible values are "survey" or "fundraising" - start_time: - type: string - description: The date to begin showing the announcement - end_time: - type: string - description: The date to stop showing the announcement - platforms: - type: array - items: + announcement: + type: object + properties: + id: + type: string + description: Unique ID of the announcement + type: + type: string + description: The type of announcement. Possible values are "survey" or "fundraising" + start_time: + type: string + description: The date to begin showing the announcement + end_time: + type: string + description: The date to stop showing the announcement + platforms: + type: array + items: + type: string + description: An array of platforms to display the announcement. Possible + values are "iOSApp" or "AndroidApp" + text: + type: string + description: The text of the announcement + image: type: string - description: An array of platforms to display the announcement. Possible values are "iOSApp" or "AndroidApp" - text: - type: string - description: The text of the announcement - image: - type: string - description: The URL of the image for the announcement - action: - type: object - description: The action for the button of the announcement - $ref: '#/definitions/action' - caption_HTML: - type: string - description: HTML to display below the announcement. Usually a privacy statment and link to a policy - countries: - type: array - items: + description: The URL of the image for the announcement + action: + $ref: '#/components/schemas/action' + caption_HTML: type: string - description: | - An array of country codes in which to display the announcement. - Clients should derive the country from 'GeoIP' portion of the Set-Cookie header - required: - - id - - type - - start_time - - end_time - - platforms - - text - - countries + description: HTML to display below the announcement. Usually a privacy statment + and link to a policy + countries: + type: array + items: + type: string + description: | + An array of country codes in which to display the announcement. + Clients should derive the country from 'GeoIP' portion of the Set-Cookie header + required: + - id + - type + - start_time + - end_time + - platforms + - text + - countries - announcementsResponse: - type: object - properties: - announce: - type: array - items: - $ref: '#/definitions/announcement' - required: - - announce + announcementsResponse: + type: object + properties: + announce: + type: array + items: + $ref: '#/components/schemas/announcement' + required: + - announce diff --git a/v1/availability.yaml b/v1/availability.yaml index 4e266db2a..7c563f717 100644 --- a/v1/availability.yaml +++ b/v1/availability.yaml @@ -1,8 +1,9 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.1-beta' + version: 1.0.1-beta title: MediaWiki featured feed content availability API - description: API for determining availbility of various featured feed content items by wiki language + description: API for determining availbility of various featured feed content items + by wiki language termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions contact: name: Reading Infrastructure @@ -20,18 +21,20 @@ paths: Gets availability of featured feed content for the apps by wiki domain. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Availability/1.0.1" - - application/problem+json responses: - '200': - description: JSON containing lists of wiki domains for which feed content is available. - schema: - $ref: '#/definitions/availability' + 200: + description: JSON containing lists of wiki domains for which feed content + is available. + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Availability/1.0.1": + schema: + $ref: '#/components/schemas/availability' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_feed_content_availability: request: @@ -42,53 +45,61 @@ paths: headers: '{{get_feed_content_availability.headers}}' body: '{{get_feed_content_availability.body}}' x-monitor: false - -# copied from MCS spec.yaml -definitions: - availability: - type: object - properties: - todays_featured_article: - type: array - description: domains for wikis with this feature enabled, or [ '*..org' ] for all wikis in a project - items: +components: + schemas: + availability: + type: object + properties: + todays_featured_article: + type: array + description: domains for wikis with this feature enabled, or [ '*..org' + ] for all wikis in a project + items: + type: string + most_read: + type: array + description: domains for wikis with this feature enabled, or [ '*..org' + ] for all wikis in a project + items: + type: string + picture_of_the_day: + type: array + description: domains for wikis with this feature enabled, or [ '*..org' + ] for all wikis in a project + items: + type: string + in_the_news: + type: array + description: domains for wikis with this feature enabled, or [ '*..org' + ] for all wikis in a project + items: + type: string + on_this_day: + type: array + description: domains for wikis with this feature enabled, or [ '*..org' + ] for all wikis in a project + items: + type: string + required: + - in_the_news + - most_read + - on_this_day + - picture_of_the_day + - todays_featured_article + problem: + required: + - type + type: object + properties: + status: + type: integer + type: type: string - most_read: - type: array - description: domains for wikis with this feature enabled, or [ '*..org' ] for all wikis in a project - items: + title: type: string - picture_of_the_day: - type: array - description: domains for wikis with this feature enabled, or [ '*..org' ] for all wikis in a project - items: + detail: type: string - in_the_news: - type: array - description: domains for wikis with this feature enabled, or [ '*..org' ] for all wikis in a project - items: + method: type: string - on_this_day: - type: array - description: domains for wikis with this feature enabled, or [ '*..org' ] for all wikis in a project - items: + uri: type: string - required: [ todays_featured_article, most_read, picture_of_the_day, in_the_news, on_this_day ] - additionalProperties: false - - problem: - required: - - type - properties: - status: - type: integer - type: - type: string - title: - type: string - detail: - type: string - method: - type: string - uri: - type: string diff --git a/v1/citoid.yaml b/v1/citoid.yaml index 63ecd9709..d450986ba 100644 --- a/v1/citoid.yaml +++ b/v1/citoid.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki Citation API description: Citation API based on the Citoid services termsOfService: https://github.com/wikimedia/restbase#restbase @@ -34,46 +34,47 @@ paths: See [bibtex.org](http://www.bibtex.org/). Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8; - - application/x-bibtex; charset=utf-8 - - application/problem+json parameters: - name: format in: path - description: "The format to use for the resulting citation data" - type: string - enum: - - mediawiki - - mediawiki-basefields - - zotero - - bibtex + description: The format to use for the resulting citation data + schema: + type: string + enum: + - mediawiki + - mediawiki-basefields + - zotero + - bibtex required: true - name: query in: path - description: > - URL of an article, DOI, ISBN, PMCID or PMID in the URL-encoded format. - Note that on the Swagger-UI doc page you don't need to URI-encode the - parameter manually, it will be done by the docs engine. - type: string + description: | + URL of an article, DOI, ISBN, PMCID or PMID in the URL-encoded format. Note that on the Swagger-UI doc page you don't need to URI-encode the parameter manually, it will be done by the docs engine. required: true + schema: + type: string - name: Accept-Language in: header - type: string - required: false - description: > - For some articles the result depends on the `Accept-Language` header, so - provide it if localized content is required. + description: | + For some articles the result depends on the `Accept-Language` header, so provide it if localized content is required. + schema: + type: string responses: - '200': + 200: description: The citation data in the requested format - schema: - $ref: '#/definitions/result' - '404': + content: + application/json; charset=utf-8;: + schema: + $ref: '#/components/schemas/result' + application/x-bibtex; charset=utf-8: + schema: + $ref: '#/components/schemas/result' + 404: description: Citation data was not found. - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' operationId: getCitation # TEMP TEMP TEMP # Citoid monitoring temporarily disabled due to T211411 @@ -93,16 +94,18 @@ paths: # - title: /.+/ # itemType: /.+/ -definitions: - result: - required: - - title - - url - - itemType - properties: - itemType: - type: string - title: - type: string - url: - type: string +components: + schemas: + result: + required: + - title + - url + - itemType + type: object + properties: + itemType: + type: string + title: + type: string + url: + type: string diff --git a/v1/common_schemas.yaml b/v1/common_schemas.yaml index 6fb22aa9e..8bcf37fd7 100644 --- a/v1/common_schemas.yaml +++ b/v1/common_schemas.yaml @@ -2,129 +2,144 @@ # It doesn't export any paths, but the HyperSwitch spec loading process will merge # schemas into the final spec, so other files can reference them. -definitions: - # A https://tools.ietf.org/html/draft-nottingham-http-problem - problem: - required: - - type - properties: - type: - type: string - title: - type: string - detail: - type: string - instance: - type: string +components: + schemas: + # A https://tools.ietf.org/html/draft-nottingham-http-problem + problem: + required: + - type + type: object + properties: + type: + type: string + title: + type: string + detail: + type: string + instance: + type: string - originalimage: - type: object - properties: - source: - type: string - description: Original image URI - width: - type: integer - description: Original image width - height: - type: integer - description: Original image height - required: ['source', 'width', 'height'] + originalimage: + type: object + properties: + source: + type: string + description: Original image URI + width: + type: integer + description: Original image width + height: + type: integer + description: Original image height + required: + - height + - source + - width - thumbnail: - type: object - properties: - source: - type: string - description: Thumbnail image URI - width: - type: integer - description: Thumbnail width - height: - type: integer - description: Thumnail height - required: ['source', 'width', 'height'] + thumbnail: + type: object + properties: + source: + type: string + description: Thumbnail image URI + width: + type: integer + description: Thumbnail width + height: + type: integer + description: Thumnail height + required: + - height + - source + - width - summary: - type: object - properties: - title: - type: string - description: The page title - displaytitle: - type: string - description: The page title how it should be shown to the user - pageid: - type: integer - description: The page ID - #timestamp: - # type: string - # format: date-time - # description: The ISO timestamp of a page revision - extract: - type: string - description: First several sentences of an article in plain text - extract_html: - type: string - description: First several sentences of an article in simple HTML format - thumbnail: - $ref: '#/definitions/thumbnail' - originalimage: - $ref: '#/definitions/originalimage' - lang: - type: string - description: The page language code - example: en - dir: - type: string - description: The page language direction code - example: ltr - timestamp: - type: string - description: The time when the page was last editted in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format - example: '1970-01-01T00:00:00.000Z' - description: - type: string - description: Wikidata description for the page - example: American poet - coordinates: - type: object - description: The coordinates of the item - properties: - lat: - type: number - description: The latitude - lon: - type: number - description: The longitude - required: [ 'lat', 'lon' ] - required: ['title', 'extract', 'lang', 'dir'] - - cx_mt: - type: object - properties: - contents: - type: string - description: the translated content - - cx_dict: - type: object - properties: - source: - type: string - description: the original word to look up - translations: - type: array - description: the translations found - items: + summary: + type: object + properties: + title: + type: string + description: The page title + displaytitle: + type: string + description: The page title how it should be shown to the user + pageid: + type: integer + description: The page ID + #timestamp: + # type: string + # format: date-time + # description: The ISO timestamp of a page revision + extract: + type: string + description: First several sentences of an article in plain text + extract_html: + type: string + description: First several sentences of an article in simple HTML format + thumbnail: + $ref: '#/components/schemas/thumbnail' + originalimage: + $ref: '#/components/schemas/originalimage' + lang: + type: string + description: The page language code + example: en + dir: + type: string + description: The page language direction code + example: ltr + timestamp: + type: string + description: The time when the page was last editted in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) + format + example: 1970-01-01T00:00:00.000Z + description: + type: string + description: Wikidata description for the page + example: American poet + coordinates: type: object + description: The coordinates of the item properties: - phrase: - type: string - description: the translated phrase - info: - type: string - description: extra information about the phrase - sources: - type: string - description: the source dictionary used for the translation + lat: + type: number + description: The latitude + lon: + type: number + description: The longitude + required: + - lat + - lon + required: + - dir + - extract + - lang + - title + + cx_mt: + type: object + properties: + contents: + type: string + description: the translated content + + cx_dict: + type: object + properties: + source: + type: string + description: the original word to look up + translations: + type: array + description: the translations found + items: + type: object + properties: + phrase: + type: string + description: the translated phrase + info: + type: string + description: extra information about the phrase + sources: + type: string + description: the source dictionary used for the translation diff --git a/v1/content.yaml b/v1/content.yaml index 2579e3031..5697e0807 100644 --- a/v1/content.yaml +++ b/v1/content.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0' + version: 1.0.0 title: MediaWiki Content API description: Basic MediaWiki content api. termsOfService: https://github.com/wikimedia/restbase#restbase @@ -22,18 +22,19 @@ paths: summary: List page-related API entry points. description: | Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable) - produces: - - application/json - - application/problem+json responses: - '200': + 200: description: A list of page-related API end points. - schema: - $ref: '#/definitions/listing' + content: + application/json: + schema: + $ref: '#/components/schemas/listing' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false /title/{title}: @@ -46,21 +47,21 @@ paths: metadata for that revision is returned, otherwise the latest revision ID is assumed. Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable). - produces: - - application/json - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string responses: - '200': + 200: description: The latest revision metadata for the provided title. - schema: - $ref: '#/definitions/revision' - '301': + content: + application/json: + schema: + $ref: '#/components/schemas/revision' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid these redirects, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -68,7 +69,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -76,14 +77,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title or no revisions found. - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: @@ -118,14 +123,16 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The revision id - type: integer required: true + schema: + type: integer x-request-handler: - get_from_backend: request: @@ -158,35 +165,30 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: sections in: query description: Comma-separated list of section IDs. - type: string + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string - produces: - - text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.7.0" - - application/json - - application/problem+json + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string responses: - '200': + 200: description: | The latest HTML for the given page title. @@ -194,8 +196,6 @@ paths: spec](https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec) for a description of the MediaWiki-specific semantic markup in this HTML. Note that additional metadata is available in the HTML head. - schema: - type: string headers: ETag: description: | @@ -206,8 +206,17 @@ paths: `base_etag` POST parameter), and can also be used to retrieve the exact corresponding data-parsoid metadata, by requesting the specific `revision` and `tid` indicated by the `ETag`. - type: string - '301': + schema: + type: string + content: + text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.7.0": + schema: + type: string + + application/json: + schema: + type: object + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -215,7 +224,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target, and the body contains the actual page contents as HTML. @@ -223,14 +232,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: @@ -296,54 +309,48 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string - required: true - - name: base_etag - in: formData - description: > - ETag header of the revision the edit is based on. Should be - supplied for all existing pages to ensure clean round-tripping. - type: string - required: false - - name: html - in: formData - description: HTML of the page to save. - type: string - required: true - x-textarea: true - - name: csrf_token - in: formData - description: CSRF edit token provided by the MW API. - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true - - name: comment - in: formData - description: Comment summarizing the change. - type: string - required: false - - name: is_minor - in: formData - description: Flag indicating a minor change. - type: boolean - required: false - - name: is_bot - in: formData - description: Flag indicating a bot edit. - type: boolean - required: false - consumes: - - multipart/form-data - produces: - - application/json - - application/problem+json + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + required: + - csrf_token + - html + properties: + base_etag: + type: string + description: | + ETag header of the revision the edit is based on. Should be supplied for all existing pages to ensure clean round-tripping. + html: + type: string + description: HTML of the page to save. + x-textarea: true + csrf_token: + type: string + description: CSRF edit token provided by the MW API. + comment: + type: string + description: Comment summarizing the change. + is_minor: + type: boolean + description: Flag indicating a minor change. + is_bot: + type: boolean + description: Flag indicating a bot edit. + required: true responses: - '200': + 200: description: The content was not changed, and no new version was created. - schema: - type: object - # FIXME: document - '201': + content: + application/json: + schema: + type: object + # FIXME: document + 201: description: A new revision of the page has been created headers: ETag: @@ -351,19 +358,26 @@ paths: ETag header indicating the new revision and timeuuid, separated by a slash: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - type: string - '400': + schema: + type: string + 400: description: Invalid request - lack of required parameters, bad ETags etc. - schema: - $ref: '#/definitions/problem' - '409': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 409: description: Edit conflict - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' # RB doesn't check for permissions, just prepares a request correctly x-route-filters: - path: ./lib/mediawiki_auth_filter.js @@ -395,43 +409,39 @@ paths: description: | Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable) operationId: getFormatRevision - produces: - - text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.7.0" - - application/json - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The revision - type: integer required: true + schema: + type: integer - name: sections in: query description: Comma-separated list of section IDs - type: string + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string responses: - '200': + 200: description: | The html for the given page, revision and tid. @@ -454,8 +464,16 @@ paths: `base_etag` POST parameter), and can also be used to retrieve the exact corresponding data-parsoid metadata, by requesting the specific `revision` and `tid` indicated by the `ETag`. - type: string - '301': + schema: + type: string + content: + text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.7.0: + schema: + type: string + application/json: + schema: + type: object + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -463,7 +481,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target, and the body contains the actual page revision contents as HTML. @@ -471,22 +489,30 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '400': + 400: description: Invalid revision or tid - schema: - $ref: '#/definitions/problem' - '403': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 403: description: Access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page, revision or tid - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: @@ -509,39 +535,40 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The revision - type: integer required: true + schema: + type: integer - name: tid in: path description: The revision's time ID - type: string required: true + schema: + type: string - name: sections in: query description: Comma-separated list of section IDs - type: string + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string x-request-handler: - get_from_backend: request: @@ -576,44 +603,45 @@ paths: provided in the `ETag` header of the HTML response. Stability: [Stable](https://www.mediawiki.org/wiki/API_versioning#Stable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/data-parsoid/1.7.0" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The revision - type: integer required: true + schema: + type: integer - name: tid in: path description: The revision's time ID - type: string required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean responses: - '200': + 200: description: The latest Parsoid data for the given page - schema: - $ref: '#/definitions/data-parsoid' headers: ETag: description: 'Revision / tid: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"' - type: string - '301': + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/data-parsoid/1.7.0": + schema: + $ref: '#/components/schemas/data-parsoid' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -621,7 +649,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target, and the body contains the actual data-parsoid for the redirect page. @@ -629,22 +657,30 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '400': + 400: description: Invalid revision - schema: - $ref: '#/definitions/problem' - '403': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 403: description: Access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page, revision or tid - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: @@ -668,23 +704,25 @@ paths: summary: Get the linter errors for a specific title/revision. description: | Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string responses: - '200': + 200: description: | The lint errors for the given page and optionally revision. See [the Linter extension docs](https://www.mediawiki.org/wiki/Extension:Linter) for more details. - '301': + content: + application/json: + schema: + type: object + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -692,7 +730,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target, and the body contains the actual page revision contents as HTML. @@ -700,22 +738,30 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '400': + 400: description: Invalid revision or tid - schema: - $ref: '#/definitions/problem' - '403': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 403: description: Access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page, revision or tid - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: @@ -730,14 +776,16 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The revision - type: integer required: true + schema: + type: integer x-request-handler: - get_from_backend: request: @@ -762,72 +810,74 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string - required: true - - name: base_etag - in: formData - description: The ETag header of the revision the edit is based on. - type: string - required: false - - name: wikitext - in: formData - description: The wikitext source of the page to save - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true - x-textarea: true - - name: csrf_token - in: formData - description: The CRSF edit token provided by the MW API - type: string - required: true - - name: comment - in: formData - description: The summary of the change - type: string - required: false - - name: is_minor - in: formData - description: Whether this represents a minor change - type: boolean - required: false - - name: is_bot - in: formData - description: Whether the change is being made by a bot - type: boolean - required: false - consumes: - - multipart/form-data - produces: - - application/json - - application/problem+json + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + required: + - csrf_token + - wikitext + properties: + base_etag: + type: string + description: The ETag header of the revision the edit is based on. + wikitext: + type: string + description: The wikitext source of the page to save + x-textarea: true + csrf_token: + type: string + description: The CRSF edit token provided by the MW API + comment: + type: string + description: The summary of the change + is_minor: + type: boolean + description: Whether this represents a minor change + is_bot: + type: boolean + description: Whether the change is being made by a bot + required: true responses: - '200': + 200: description: The existing revision of the page matches the sent text - '201': + 201: description: A new revision of the page has been created - schema: - type: object - # FIXME: document + content: + application/json: + schema: + type: object + # FIXME: document headers: ETag: description: | ETag header indicating the new revision and timeuuid, separated by a slash: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - type: string - '400': + schema: + type: string + 400: description: Invalid request - lack of required parameters, bad ETags etc. - schema: - $ref: '#/definitions/problem' - '409': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 409: description: Edit conflict - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' # RB doesn't check for permissions, just prepares a request correctly x-route-filters: - path: ./lib/mediawiki_auth_filter.js @@ -839,103 +889,107 @@ paths: body: '{{request.body}}' x-monitor: false - -definitions: - revisions: - description: The result format for revision listing - required: - - items - properties: - items: - type: array - $ref: '#/definitions/revisionIdentifier' - - listing: - description: The result format for listings - required: - - items - properties: - items: - type: array +components: + schemas: + revisions: + description: The result format for revision listing + required: + - items + type: object + properties: items: - type: string - _links: - type: object - properties: - next: - type: object - properties: - href: - type: string - description: Relative link to next result page. - - data-parsoid: - description: Result format for Parsoid data queries - required: - - counter - - ids - properties: - counter: - type: integer - format: int32 - ids: - type: object - - revision: - description: Result format for revision items - required: - - count - - items - properties: - count: - type: integer - format: int32 - items: - type: array - $ref: '#/definitions/revisionInfo' - - revisionInfo: - type: object - description: Complete information about the revision - properties: - title: - type: string - page_id: - type: integer - format: int32 - rev: - type: integer - format: int32 - tid: - type: string - comment: - type: string - restrictions: - type: array + $ref: '#/components/schemas/revisionIdentifier' + + listing: + description: The result format for listings + required: + - items + type: object + properties: items: - type: string - tags: - type: array + type: array + items: + type: string + _links: + type: object + properties: + next: + type: object + properties: + href: + type: string + description: Relative link to next result page. + + data-parsoid: + description: Result format for Parsoid data queries + required: + - counter + - ids + type: object + properties: + counter: + type: integer + format: int32 + ids: + type: object + properties: {} + + revision: + description: Result format for revision items + required: + - count + - items + type: object + properties: + count: + type: integer + format: int32 items: + $ref: '#/components/schemas/revisionInfo' + + revisionInfo: + type: object + description: Complete information about the revision + properties: + title: + type: string + page_id: + type: integer + format: int32 + rev: + type: integer + format: int32 + tid: + type: string + comment: + type: string + restrictions: + type: array + items: + type: string + tags: + type: array + items: + type: string + user_id: + type: integer + format: int32 + user_text: + type: string + timestamp: + type: string + format: date-time + redirect: + type: boolean + page_language: + type: string + + revisionIdentifier: + type: object + description: Unique revision identifier + properties: + revision: + type: integer + format: int32 + tid: type: string - user_id: - type: integer - format: int32 - user_text: - type: string - timestamp: - type: string - format: date-time - redirect: - type: boolean - page_language: - type: string - - revisionIdentifier: - description: Unique revision identifier - properties: - revision: - type: integer - format: int32 - tid: - type: string diff --git a/v1/content_segments.yaml b/v1/content_segments.yaml index ddcbc7d08..e87572edf 100644 --- a/v1/content_segments.yaml +++ b/v1/content_segments.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0' + version: 1.0.0 title: MediaWiki Section Content API description: Adding translated section content to the content API. tags: @@ -18,49 +18,57 @@ paths: API](https://wikimedia.org/api/rest_v1/#!/Transform). Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string responses: - '200': + 200: description: The segmented page for the given title and revision - schema: - type: object - properties: - sourceLanguage: - type: string - description: The source language of the page - title: - type: string - description: The title of the segmented page returned - revision: - type: integer - description: The revision ID of the segmented page - segmentedContent: - type: string - description: The segmented HTML body of the contents of the page - '400': + content: + application/json: + schema: + type: object + properties: + sourceLanguage: + type: string + description: The source language of the page + title: + type: string + description: The title of the segmented page returned + revision: + type: integer + description: The revision ID of the segmented page + segmentedContent: + type: string + description: The segmented HTML body of the contents of the page + 400: description: Invalid revision - schema: - $ref: '#/definitions/problem' - '403': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 403: description: Access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page or revision - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_cx: request: @@ -73,11 +81,13 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The revision id - type: integer required: true + schema: + type: integer diff --git a/v1/css.yaml b/v1/css.yaml index dbfb734a2..c12d3f8e0 100644 --- a/v1/css.yaml +++ b/v1/css.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: CSS for mobile apps description: API for retrieving CSS for mobile apps termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -29,30 +29,35 @@ paths: For these we suggest meta.wikimedia.org. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/CSS/1.0.0" - - application/problem+json parameters: - name: type in: path description: The desired CSS bundle - type: string - enum: - - base - - pagelib - - site + schema: + type: string + enum: + - base + - pagelib + - site required: true responses: - '200': + 200: description: Success headers: ETag: - type: string description: Different values indicate that the content has changed + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/CSS/1.0.0": + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_pcs: request: @@ -61,6 +66,6 @@ paths: return: status: 200 headers: '{{ merge({"cache-control": options.response_cache_control}, - get_from_pcs.headers) }}' + get_from_pcs.headers) }}' body: '{{get_from_pcs.body}}' x-monitor: false diff --git a/v1/definition.yaml b/v1/definition.yaml index 0c8c38e81..b7e9acc69 100644 --- a/v1/definition.yaml +++ b/v1/definition.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki Definition API description: Wikitionary word definition API termsOfService: https://github.com/wikimedia/restbase#restbase @@ -31,30 +31,28 @@ paths: for background and considerations for further development. Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/definition/0.8.0" - - application/problem+json parameters: - name: term in: path description: The term to define - type: string required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean responses: - '200': + 200: description: The definition for the given term - schema: - $ref: '#/definitions/definitionsResponse' - '301': + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/definition/0.8.0": + schema: + $ref: '#/components/schemas/definitionsResponse' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -62,7 +60,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -70,27 +68,31 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown term - schema: - $ref: '#/definitions/problem' - '501': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 501: description: Term definitions not supported for this language - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-setup-handler: # Set up a simple key-value bucket. - init: - method: 'put' + method: put uri: /{domain}/sys/key_value/term.definition-ng body: - valueType: 'json' - + valueType: json x-request-handler: - storage: request: @@ -101,8 +103,7 @@ paths: catch: status: 404 return_if: - # Typical case: Return straight from storage. - status: '2xx' + status: 2xx return: status: 200 headers: @@ -175,38 +176,43 @@ paths: etag: /.+/ content-type: /^application\/json/ -definitions: - definition: - type: object - description: Describes a single definition of a term - properties: - definition: - type: string - description: A term definition - examples: - type: array - items: +components: + schemas: + definition: + type: object + description: Describes a single definition of a term + properties: + definition: type: string - description: An example of word usage - required: [ 'definition' ] + description: A term definition + examples: + type: array + items: + type: string + description: An example of word usage + required: + - definition - usageDescription: - type: object - properties: - partOfSpeech: - type: string - description: Part of speech (e.g. 'Noun' or 'Verb') - definitions: - type: array - items: - $ref: definition - required: [ 'partOfSpeech', 'definitions' ] + usageDescription: + type: object + properties: + partOfSpeech: + type: string + description: Part of speech (e.g. 'Noun' or 'Verb') + definitions: + type: array + items: + $ref: '#/components/schemas/definition' + required: + - definitions + - partOfSpeech - definitionsResponse: - type: object - properties: - usages: - type: array - items: - $ref: usageDescription - required: [ 'usages' ] + definitionsResponse: + type: object + properties: + usages: + type: array + items: + $ref: '#/components/schemas/usageDescription' + required: + - usages diff --git a/v1/feed.yaml b/v1/feed.yaml index f4fb5db05..d235a1b52 100644 --- a/v1/feed.yaml +++ b/v1/feed.yaml @@ -15,34 +15,38 @@ paths: content and the featured image and video of the day. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: yyyy in: path - description: 'Year the aggregated content is requested for' - type: string + description: Year the aggregated content is requested for required: true + schema: + type: string - name: mm in: path - description: 'Month the aggregated content is requested for, 0-padded' - type: string + description: Month the aggregated content is requested for, 0-padded required: true + schema: + type: string - name: dd in: path - description: 'Day of the month the aggregated content is requested for, 0-padded' - type: string + description: Day of the month the aggregated content is requested for, 0-padded required: true + schema: + type: string responses: - '200': + 200: description: JSON containing all of the featured content - schema: - $ref: '#/definitions/feed' + content: + application/json: + schema: + $ref: '#/components/schemas/feed' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' operationId: aggregatedFeed x-monitor: true x-amples: @@ -50,9 +54,9 @@ paths: request: params: domain: en.wikipedia.org - yyyy: '2016' - mm: '04' - dd: '29' + yyyy: "2016" + mm: "04" + dd: "29" response: status: 200 headers: @@ -87,136 +91,127 @@ paths: source: /.+/ width: /.+/ height: /.+/ +components: + schemas: + mostread_article: + type: object + properties: + title: + type: string + description: Article title in a form of DB key + normalizedtitle: + type: string + description: Article title as it should be presented to the user + views: + type: integer + description: Number of views on the requested day + rank: + type: integer + description: Position in the list of most viewed articles + thumbnail: + $ref: '#/components/schemas/thumbnail' + description: + type: string + description: Wikidata description of the article + extract: + type: string + description: First several sentences of an article in plain text + required: + - title + - normalizedtitle + - views + - rank -definitions: - mostread_article: - type: object - properties: - title: - type: string - description: Article title in a form of DB key - normalizedtitle: - type: string - description: Article title as it should be presented to the user - views: - type: integer - description: Number of views on the requested day - rank: - type: integer - description: Position in the list of most viewed articles - thumbnail: - description: Lead image for the article - $ref: '#/definitions/thumbnail' - description: - type: string - description: Wikidata description of the article - extract: - type: string - description: First several sentences of an article in plain text - required: - - title - - normalizedtitle - - views - - rank - - mostread: - type: object - properties: - date: - type: string - description: The date which the data correspond to - articles: - type: array - description: Array of most popular articles - items: - $ref: '#/definitions/mostread_article' - required: - - date - - articles - - news_item: - type: object - properties: - story: - type: string - description: A cover story for the news item - links: - type: array - description: A collection of articles related to the news item - items: - $ref: '#/definitions/summary' - required: - - story - - links - - news: - type: array - items: - $ref: '#/definitions/news_item' + mostread: + type: object + properties: + date: + type: string + description: The date which the data correspond to + articles: + type: array + description: Array of most popular articles + items: + $ref: '#/components/schemas/mostread_article' + required: + - date + - articles - image_description: - properties: - text: - type: string - description: Text of the description - lang: - type: string - description: Language code of the description - required: - - text - - lang + news_item: + type: object + properties: + story: + type: string + description: A cover story for the news item + links: + type: array + description: A collection of articles related to the news item + items: + $ref: '#/components/schemas/summary' + required: + - story + - links - image: - type: object - properties: - title: - type: string - description: Image title - thumbnail: - description: Image thumbnail - $ref: '#/definitions/thumbnail' - image: - description: Full-size image - $ref: '#/definitions/thumbnail' - description: - description: Description of an image - $ref: '#/definitions/image_description' - required: - - title - - thumbnail - - image + news: + type: array + items: + $ref: '#/components/schemas/news_item' - onthisday: - type: array - items: + image_description: type: object properties: text: type: string - description: Short description of the event - pages: - type: array - description: List of pages related to the event - items: - $ref: '#/definitions/summary' + description: Text of the description + lang: + type: string + description: Language code of the description + required: + - text + - lang - feed: - type: object - description: Aggregated feed content for a given date - properties: - tfa: - description: Data about the featured article of the day - $ref: '#/definitions/summary' - mostread: - description: Data about most viewed articles - $ref: '#/definitions/mostread' - news: - description: Data about in the news section - $ref: '#/definitions/news' - image: - description: Featured image for a given date - $ref: '#/definitions/image' - onthisday: - description: List of featured events that happend on this day - $ref: '#/definitions/onthisday' - additionalProperties: false + image: + type: object + properties: + title: + type: string + description: Image title + thumbnail: + $ref: '#/components/schemas/thumbnail' + image: + $ref: '#/components/schemas/thumbnail' + description: + $ref: '#/components/schemas/image_description' + required: + - title + - thumbnail + - image + + onthisday: + type: array + items: + type: object + properties: + text: + type: string + description: Short description of the event + pages: + type: array + description: List of pages related to the event + items: + $ref: '#/components/schemas/summary' + + feed: + type: object + description: Aggregated feed content for a given date + properties: + tfa: + $ref: '#/components/schemas/summary' + mostread: + $ref: '#/components/schemas/mostread' + news: + $ref: '#/components/schemas/news' + image: + $ref: '#/components/schemas/image' + onthisday: + $ref: '#/components/schemas/onthisday' diff --git a/v1/graphoid.yaml b/v1/graphoid.yaml index 1fdf24513..4cc240e68 100644 --- a/v1/graphoid.yaml +++ b/v1/graphoid.yaml @@ -11,48 +11,56 @@ paths: for details. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - image/png - - application/problem+json parameters: - name: title in: path description: The page title - type: string required: true + schema: + type: string - name: revision in: path description: The page revision, or 0 for the latest - type: integer required: true + schema: + type: integer - name: graph_id in: path description: The graph ID, consisting of a hash and the suffix `.png`. - type: string required: true + schema: + type: string responses: - '200': + 200: description: The PNG render of the requested graph. - schema: - type: file + content: + image/png: + schema: + type: string + format: binary # FIXME: Actually return a decent ETag from graphoid & document it here! # See https://phabricator.wikimedia.org/T125924 #headers: # ETag: # type: string - '403': + 403: description: access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page title or revision - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_graphoid: request: diff --git a/v1/javascript.yaml b/v1/javascript.yaml index aa764fbc3..908cda2ee 100644 --- a/v1/javascript.yaml +++ b/v1/javascript.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: JavaScript bundle from the wikimedia-page-library description: API for retrieving JavaScript for mobile apps termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -27,20 +27,24 @@ paths: * code for collapsing and expanding tables. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/JavaScript/1.0.0" - - application/problem+json responses: - '200': + 200: description: Success headers: ETag: - type: string description: Different values indicate that the content has changed + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/JavaScript/1.0.0": + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_pcs: request: @@ -49,6 +53,6 @@ paths: return: status: 200 headers: '{{ merge({"cache-control": options.response_cache_control}, - get_from_pcs.headers) }}' + get_from_pcs.headers) }}' body: '{{get_from_pcs.body}}' x-monitor: false diff --git a/v1/lists.yaml b/v1/lists.yaml index b0a37d665..6ff5fba10 100644 --- a/v1/lists.yaml +++ b/v1/lists.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '0.1' + version: 0.1 title: MediaWiki Reading Lists API description: API for manipulating private [reading lists](https://www.mediawiki.org/wiki/Reading/Reading_Lists) termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -20,9 +20,10 @@ x-yaml-anchors: name: csrf_token in: query required: true - type: string + schema: + type: string + example: "f63c343876da566045e6b59c4532450559c828d3+\\" description: "The CRSF edit token provided by the MediaWiki API" -# example: "f63c343876da566045e6b59c4532450559c828d3+\\" list_common: &list_common name: type: string @@ -34,11 +35,11 @@ x-yaml-anchors: project: &list_entry_common_project type: string description: 'Domain of the wiki containing the page.' -# example: 'https://en.wikipedia.org' + example: 'https://en.wikipedia.org' title: &list_entry_common_title type: string description: 'Title of the page containing the page, in database format.' -# example: Barack_Obama + example: Barack_Obama paths: /lists/setup: post: @@ -51,18 +52,21 @@ paths: Request must be authenticated with a MediaWiki session cookie. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - <<: *csrf_token responses: - '200': + 200: description: Success. + content: + application/json; charset=utf-8: + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -87,18 +91,21 @@ paths: Request must be authenticated with a MediaWiki session cookie. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - <<: *csrf_token responses: - '200': + 200: description: Success. + content: + application/json; charset=utf-8: + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -128,44 +135,47 @@ paths: - name: next in: query description: Continuation parameter from previous request - type: string - required: false + schema: + type: string - name: sort in: query description: | Sort order - `name`: by name, ascending; - `updated`: by last modification date, descending. - type: string - default: updated - enum: [ name, updated ] - required: false - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - - application/problem+json + schema: + type: string + default: updated + enum: + - name + - updated responses: - '200': + 200: description: An array of list metadata. - schema: - type: object - properties: - lists: - type: array - items: - $ref: '#/definitions/list_read' - next: - type: string - description: Continuation token. - continue-from: - type: string - format: date-time - description: | - Timestamp to sync from, to be used with the `GET /lists/changes/since/{date}` - endpoint. + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1": + schema: + type: object + properties: + lists: + type: array + items: + $ref: '#/components/schemas/list_read' + next: + type: string + description: Continuation token. + continue-from: + type: string + format: date-time + description: | + Timestamp to sync from, to be used with the `GET /lists/changes/since/{date}` + endpoint. default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -184,7 +194,7 @@ paths: status: 200 headers: content-type: application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - cache-control: "max-age=0, s-maxage=0" + cache-control: max-age=0, s-maxage=0 body: lists: '{{forward_to_mw.body.query.readinglists}}' next: '{{flattenContinuation(forward_to_mw.body.continue)}}' @@ -205,38 +215,40 @@ paths: This endpoint is deprecated and might be removed without warning. Use the batch version instead. x-maxsize: *maxEntriesPerList - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - - name: list - in: body - required: true - schema: - $ref: '#/definitions/list_write' - <<: *csrf_token + requestBody: + content: + '*/*': + schema: + $ref: '#/components/schemas/list_write' + required: true responses: - '200': + 200: description: The data for the new list. - schema: - type: object - properties: - id: - type: integer - description: | - List ID. + content: + application/json; charset=utf-8: + schema: + type: object + properties: + id: + type: integer + description: | + List ID. - Deprecated, will be removed. Use the full list object. - example: 7 - list: - $ref: '#/definitions/list_read' - required: - - id - - list + Deprecated, will be removed. Use the full list object. + example: 7 + list: + $ref: '#/components/schemas/list_read' + required: + - id + - list default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -270,39 +282,43 @@ paths: parameters: - name: id in: path - type: integer -# example: 42 required: true - - name: list - in: body schema: - $ref: '#/definitions/list_write' + type: integer + example: 42 - <<: *csrf_token - produces: - - application/json; charset=utf-8 - - application/problem+json + requestBody: + content: + '*/*': + schema: + $ref: '#/components/schemas/list_write' + required: false responses: - '200': + 200: description: The updated data for the list. - schema: - type: object - properties: - id: - type: integer - description: | - List ID. + content: + application/json; charset=utf-8: + schema: + type: object + properties: + id: + type: integer + description: | + List ID. - Deprecated, will be removed. Use the full list object. - example: 7 - list: - $ref: '#/definitions/list_read' - required: - - id - - list + Deprecated, will be removed. Use the full list object. + example: 7 + list: + $ref: '#/components/schemas/list_read' + required: + - id + - list default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -333,23 +349,26 @@ paths: a MediaWiki session cookie. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - name: id in: path - type: integer -# example: 42 required: true - - <<: *csrf_token + schema: + type: integer + example: 42 responses: - '200': + 200: description: Success. + content: + application/json; charset=utf-8: + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -374,55 +393,59 @@ paths: Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) x-maxsize: *maxEntriesPerList - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - - name: batch - in: body - required: true - schema: - title: batch - type: object - required: ['batch'] - properties: - batch: - type: array - maxItems: *maxItemsPerBatch - items: - title: list - $ref: '#/definitions/list_write' - <<: *csrf_token + requestBody: + content: + '*/*': + schema: + title: batch + required: + - batch + type: object + properties: + batch: + maxItems: *maxItemsPerBatch + type: array + items: + $ref: '#/components/schemas/list_write' + required: true responses: - '200': + 200: description: The data for the new lists (in the same order as the inputs). - schema: - title: list_create_batch - type: object - properties: - batch: - type: array - description: Deprecated, will be removed. Use the full list objects instead. - items: - title: list_id - type: object - required: ['id'] - properties: - id: - type: integer - description: List ID - example: 7 - lists: - type: array - items: - $ref: '#/definitions/list_read' - required: - - batch - - lists + content: + application/json; charset=utf-8: + schema: + title: list_create_batch + type: object + properties: + batch: + type: array + description: Deprecated, will be removed. Use the full list objects + instead. + items: + title: list_id + type: object + required: + - id + properties: + id: + type: integer + description: List ID + example: 7 + lists: + type: array + items: + $ref: '#/components/schemas/list_read' + required: + - batch + - lists default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -458,44 +481,48 @@ paths: parameters: - name: id in: path - type: integer -# example: 42 required: true + schema: + type: integer + example: 42 - name: next in: query description: Continuation parameter from previous request - type: string - required: false + schema: + type: string - name: sort in: query description: | Sort order - `name`: by page title, ascending; - `updated`: by last modification date, descending. - type: string - default: updated - enum: [ name, updated ] - required: false - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - - application/problem+json + schema: + type: string + default: updated + enum: + - name + - updated responses: - '200': + 200: description: An array of list entries. - schema: - type: object - properties: - entries: - type: array - items: - $ref: '#/definitions/list_entry_read' - next: - type: string - description: Continuation token. + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1": + schema: + type: object + properties: + entries: + type: array + items: + $ref: '#/components/schemas/list_entry_read' + next: + type: string + description: Continuation token. default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' operationId: getListEntries x-route-filters: - path: ./lib/mediawiki_auth_filter.js @@ -516,43 +543,46 @@ paths: This endpoint is deprecated and might be removed without warning. Use the batch version instead. x-maxsize: *maxListsPerUser - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - name: id in: path - type: integer -# example: 42 - required: true - - name: list_entry - in: body required: true schema: - $ref: '#/definitions/list_entry_write' + type: integer + example: 42 - <<: *csrf_token + requestBody: + content: + '*/*': + schema: + $ref: '#/components/schemas/list_entry_write' + required: true responses: - '200': + 200: description: The data for the new list entry. - schema: - type: object - properties: - id: - type: integer - description: | - List entry ID + content: + application/json; charset=utf-8: + schema: + type: object + properties: + id: + type: integer + description: | + List entry ID - Deprecated, will be removed. Use the full entry object instead. - example: 13 - entry: - $ref: '#/definitions/list_entry_read' - required: - - id - - entry + Deprecated, will be removed. Use the full entry object instead. + example: 13 + entry: + $ref: '#/components/schemas/list_entry_read' + required: + - id + - entry default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -589,25 +619,29 @@ paths: parameters: - name: id in: path - type: integer -# example: 42 required: true + schema: + type: integer + example: 42 - name: entry_id in: path - type: integer -# example: 64 required: true - - <<: *csrf_token - produces: - - application/json; charset=utf-8 - - application/problem+json + schema: + type: integer + example: 64 responses: - '200': + 200: description: Success. + content: + application/json; charset=utf-8: + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -632,55 +666,60 @@ paths: Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) x-maxsize: *maxListsPerUser - produces: - - application/json; charset=utf-8 - - application/problem+json parameters: - name: id in: path - type: integer -# example: 42 - required: true - - name: batch - in: body required: true schema: - type: object - required: ['batch'] - properties: - batch: - title: list_entries - type: array - maxItems: *maxItemsPerBatch - items: - $ref: '#/definitions/list_entry_write' + type: integer + example: 42 - <<: *csrf_token + requestBody: + content: + '*/*': + schema: + type: object + required: + - batch + properties: + batch: + title: list_entries + type: array + maxItems: *maxItemsPerBatch + items: + $ref: '#/components/schemas/list_entry_write' + required: true responses: - '200': - description: The data for the new list entries (in the same order as the inputs). - schema: - type: object - properties: - batch: - type: array - items: - type: object - properties: - id: - type: integer - description: List entry ID - example: 13 - entries: - type: array - items: - $ref: '#/definitions/list_entry_read' - required: - - entries - - batch + 200: + description: The data for the new list entries (in the same order as the + inputs). + content: + application/json; charset=utf-8: + schema: + type: object + properties: + batch: + type: array + items: + type: object + properties: + id: + type: integer + description: List entry ID + example: 13 + entries: + type: array + items: + $ref: '#/components/schemas/list_entry_read' + required: + - entries + - batch default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -713,37 +752,40 @@ paths: parameters: - name: project in: path - <<: *list_entry_common_project + schema: + <<: *list_entry_common_project required: true - name: title in: path - <<: *list_entry_common_title + schema: + <<: *list_entry_common_title required: true - name: next in: query description: Continuation parameter from previous request - type: string - required: false - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - - application/problem+json + schema: + type: string responses: - '200': + 200: description: An array of list metadata. - schema: - type: object - properties: - lists: - type: array - items: - $ref: '#/definitions/list_read' - next: - type: string - description: Continuation token. + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1": + schema: + type: object + properties: + lists: + type: array + items: + $ref: '#/components/schemas/list_read' + next: + type: string + description: Continuation token. default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -762,7 +804,7 @@ paths: status: 200 headers: content-type: application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - cache-control: "max-age=0, s-maxage=0" + cache-control: max-age=0, s-maxage=0 body: lists: '{{forward_to_mw.body.query.readinglists}}' next: '{{flattenContinuation(forward_to_mw.body.continue)}}' @@ -790,40 +832,42 @@ paths: description: | Cutoff date (in ISO 8601). To ensure reliable synchronization, the API might return changes which are slightly older than the cutoff date. - type: string - format: date-time + schema: + type: string + format: date-time required: true - name: next in: query description: Continuation parameter from previous request - type: string - required: false - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - - application/problem+json + schema: + type: string responses: - '200': + 200: description: An array of list and entry metadata. - schema: - type: object - properties: - lists: - type: array - items: - $ref: '#/definitions/list_read' - next: - type: string - description: Continuation token. - continue-from: - type: string - format: date-time - description: | - Timestamp to sync from, to be used with the `GET /lists/changes/since/{date}` - endpoint. + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1": + schema: + type: object + properties: + lists: + type: array + items: + $ref: '#/components/schemas/list_read' + next: + type: string + description: Continuation token. + continue-from: + type: string + format: date-time + description: | + Timestamp to sync from, to be used with the `GET /lists/changes/since/{date}` + endpoint. default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - path: ./lib/mediawiki_auth_filter.js x-request-handler: @@ -849,7 +893,7 @@ paths: status: 200 headers: content-type: application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Lists/0.1" - cache-control: "max-age=0, s-maxage=0" + cache-control: max-age=0, s-maxage=0 body: lists: '{{forward_to_mw.body.query.readinglists}}' entries: '{{forward_to_mw.body.query.readinglistentries}}' @@ -862,55 +906,56 @@ tags: externalDocs: description: Project documentation url: https://www.mediawiki.org/wiki/Reading/Reading_Lists -definitions: - list_read: - title: list - type: object - properties: - id: - type: integer - example: 42 - <<: *list_common - created: - type: string - format: date-time - description: "Creation date (in ISO 8601)" - updated: - type: string - format: date-time - description: "Last modification date (in ISO 8601)" - required: - - id - - name - - created - - updated - list_write: - title: list - type: object - properties: - <<: *list_common - required: - - name - list_entry_read: - title: list_entry - type: object - properties: - id: - type: integer - example: 64 - <<: *list_entry_common - created: - type: string - format: date-time - description: "Creation date (in ISO 8601)" - updated: - type: string - format: date-time - description: "Last modification date (in ISO 8601)" - list_entry_write: - type: object - properties: - <<: *list_entry_common - required: - - project - - title +components: + schemas: + list_read: + title: list + type: object + properties: + id: + type: integer + example: 42 + <<: *list_common + created: + type: string + format: date-time + description: "Creation date (in ISO 8601)" + updated: + type: string + format: date-time + description: "Last modification date (in ISO 8601)" + required: + - id + - name + - created + - updated + list_write: + title: list + type: object + properties: + <<: *list_common + required: + - name + list_entry_read: + title: list_entry + type: object + properties: + id: + type: integer + example: 64 + <<: *list_entry_common + created: + type: string + format: date-time + description: "Creation date (in ISO 8601)" + updated: + type: string + format: date-time + description: "Last modification date (in ISO 8601)" + list_entry_write: + type: object + properties: + <<: *list_entry_common + required: + - project + - title diff --git a/v1/mathoid.yaml b/v1/mathoid.yaml index 9b0cc3915..b0202c76a 100644 --- a/v1/mathoid.yaml +++ b/v1/mathoid.yaml @@ -5,7 +5,8 @@ tags: paths: /math/check/{type}: post: - tags: ['Math'] + tags: + - Math summary: Check and normalize a TeX formula. description: | Checks the supplied TeX formula for correctness and returns the @@ -17,35 +18,47 @@ paths: and perform a GET request against that URL. Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable). - produces: - - application/json - - application/problem+json parameters: - name: type in: path description: The input type of the given formula; can be tex or inline-tex - type: string - required: true - enum: - - tex - - inline-tex - - chem - - name: q - in: formData - description: The formula to check - type: string required: true + schema: + type: string + enum: + - tex + - inline-tex + - chem + requestBody: + content: + multipart/form-data: + schema: + required: + - q + properties: + q: + type: string + description: The formula to check + required: true responses: - '200': + 200: description: Information about the checked formula - '400': + content: + application/json: + schema: + type: object + 400: description: Invalid type - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: true x-amples: - title: Mathoid - check test formula @@ -60,7 +73,7 @@ paths: headers: content-type: /^application\/json/ x-resource-location: /.+/ - cache-control: 'no-cache' + cache-control: no-cache body: success: true checked: /.+/ @@ -74,34 +87,41 @@ paths: /math/formula/{hash}: get: - tags: ['Math'] + tags: + - Math summary: Get a previously-stored formula description: | Returns the previously-stored formula via `/media/math/check/{type}` for the given hash. Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable). - produces: - - application/json - - application/problem+json parameters: - name: hash in: path description: The hash string of the previous POST data - type: string required: true - minLength: 1 + schema: + minLength: 1 + type: string responses: - '200': + 200: description: Information about the checked formula - '404': + content: + application/json: + schema: + type: object + 404: description: Data for the given hash cannot be found - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false x-request-handler: - get_from_sys: @@ -112,7 +132,8 @@ paths: /math/render/{format}/{hash}: get: - tags: ['Math'] + tags: + - Math summary: Get rendered formula in the given format. description: | Given a request hash, renders a TeX formula into its mathematic @@ -122,38 +143,52 @@ paths: obtained, this endpoint has to be used to obtain the actual render. Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable). - produces: - - image/svg+xml - - application/mathml+xml - - image/png - - application/problem+json parameters: - name: format in: path description: The output format; can be svg or mml - type: string required: true - enum: - - svg - - mml - - png + schema: + type: string + enum: + - svg + - mml + - png - name: hash in: path description: The hash string of the previous POST data - type: string required: true - minLength: 1 + schema: + minLength: 1 + type: string responses: - '200': + 200: description: The rendered formula - '404': + content: + image/svg+xml: + schema: + type: string + format: binary + application/mathml+xml: + schema: + type: string + format: binary + image/png: + schema: + type: string + format: binary + 404: description: Unknown format or hash ID - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false x-setup-handler: - init_svg: @@ -181,7 +216,7 @@ paths: catch: status: 404 return_if: - status: '2xx' + status: 2xx return: status: 200 headers: "{{ merge({ 'cache-control': options.cache-control }, check_storage.headers) }}" diff --git a/v1/media.yaml b/v1/media.yaml index 3431981d4..339359ca9 100644 --- a/v1/media.yaml +++ b/v1/media.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki page media API description: API for retrieving data about media items appearing on a given page termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -26,36 +26,35 @@ paths: given wiki page. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Media/1.3.1" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false - responses: - '200': - description: JSON containing metadata of media items appearing on the given page. schema: - $ref: '#/definitions/media_list' + type: boolean + responses: + 200: + description: JSON containing metadata of media items appearing on the given + page. headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Media/1.3.1": + schema: + $ref: '#/components/schemas/media_list' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -63,7 +62,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -71,14 +70,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_pcs: request: @@ -89,7 +92,7 @@ paths: return: status: 200 headers: '{{ merge({"cache-control": options.response_cache_control}, - get_from_pcs.headers) }}' + get_from_pcs.headers) }}' body: '{{get_from_pcs.body}}' x-monitor: false @@ -101,183 +104,188 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false - -# copied from MCS spec.yaml -definitions: - media_list: - type: object - properties: - revision: - type: string - description: the revision ID used to create the list - tid: - type: string - description: the time uuid of the page rendering used to create the list - items: - type: array - description: a list of media items + schema: + type: boolean +components: + schemas: + media_list: + type: object + properties: + revision: + type: string + description: the revision ID used to create the list + tid: + type: string + description: the time uuid of the page rendering used to create the list items: - $ref: '#/definitions/media_item' - required: - - revision - - tid - - items + type: array + description: a list of media items + items: + $ref: '#/components/schemas/media_item' + required: + - revision + - tid + - items - media_item: - type: object - properties: - titles: - $ref: '#/definitions/titles_set' - thumbnail: - type: object - properties: - source: - type: string - description: thumb URL - width: - type: integer - description: thumb width - height: - type: integer - description: thumb height - mime: - type: string - description: thumb MIME type - original: - type: object - properties: - source: - type: string - description: original URL - width: - type: integer - description: original width - height: - type: integer - description: original height - mime: - type: string - description: original MIME type - size: - type: integer - description: the original file size in bytes (sizes are not provided for video derivatives) - page_count: - type: integer - description: page count, if the item is a paged item (PDF, TIFF, DjVu, etc.) - file_page: - type: string - description: Full URL to the file page for the item on Wikimedia Commons - type: - type: string - enum: - - image - - video - - audio - caption: - type: object - properties: - html: - type: string - description: on-wiki caption for the media item, including all HTML markup - text: - type: string - description: plain text of the on-wiki caption for the media item - start_time: - type: number - description: start time (if any) for the media item - end_time: - type: number - description: end time (if any) for the media item - duration: - type: number - description: the playback duration in seconds (for audio and video items) - sources: - type: array - description: a list of derivatives of the original file (applies only to videos) - items: + media_item: + type: object + properties: + titles: + $ref: '#/components/schemas/titles_set' + thumbnail: type: object - artist: - type: object - description: structured info about the author of the media item - properties: - html: - type: string - description: HTML string describing the artist - name: - type: string - description: the plain text artist name, if available - user_page: - type: string - description: Wikimedia Commons user page for the artist, if available - required: - - html - credit: - type: string - description: source of the media item - license: - type: object - description: license under which the media item is available on Wikimedia Commons - properties: - type: - type: string - description: license type - url: - type: string - description: URL describing the terms and conditions of the license, if any - required: - - type - license_url: - type: string - description: URL for the pertinent license - description: - type: object - description: description of the image from Wikimedia Commons - properties: - html: - type: string - description: html image description - text: - type: string - description: plain text image description - required: [ html, text ] - required: - - titles - - file_page - - type + properties: + source: + type: string + description: thumb URL + width: + type: integer + description: thumb width + height: + type: integer + description: thumb height + mime: + type: string + description: thumb MIME type + original: + type: object + properties: + source: + type: string + description: original URL + width: + type: integer + description: original width + height: + type: integer + description: original height + mime: + type: string + description: original MIME type + size: + type: integer + description: the original file size in bytes (sizes are not provided + for video derivatives) + page_count: + type: integer + description: page count, if the item is a paged item (PDF, TIFF, DjVu, etc.) + file_page: + type: string + description: Full URL to the file page for the item on Wikimedia Commons + type: + type: string + enum: + - image + - video + - audio + caption: + type: object + properties: + html: + type: string + description: on-wiki caption for the media item, including all HTML + markup + text: + type: string + description: plain text of the on-wiki caption for the media item + start_time: + type: number + description: start time (if any) for the media item + end_time: + type: number + description: end time (if any) for the media item + duration: + type: number + description: the playback duration in seconds (for audio and video items) + sources: + type: array + description: a list of derivatives of the original file (applies only to + videos) + items: + type: object + properties: {} + artist: + type: object + description: structured info about the author of the media item + properties: + html: + type: string + description: HTML string describing the artist + name: + type: string + description: the plain text artist name, if available + user_page: + type: string + description: Wikimedia Commons user page for the artist, if available + required: + - html + credit: + type: string + description: source of the media item + license: + type: object + description: license under which the media item is available on Wikimedia + Commons + properties: + type: + type: string + description: license type + url: + type: string + description: URL describing the terms and conditions of the license, + if any + required: + - type + license_url: + type: string + description: URL for the pertinent license + description: + type: object + description: description of the image from Wikimedia Commons + properties: + html: + type: string + description: html image description + text: + type: string + description: plain text image description + required: + - html + - text + required: + - titles + - file_page + - type - titles_set: - type: object - properties: - canonical: - type: string - description: the DB key (non-prefixed) - normalized: - type: string - description: the normalized title (https://www.mediawiki.org/wiki/API:Query#Title_normalization) - display: - type: string - description: the title as it should be displayed to the user - required: - - canonical - - normalized - - display - additionalProperties: false + titles_set: + type: object + properties: + canonical: + type: string + description: the DB key (non-prefixed) + normalized: + type: string + description: the normalized title (https://www.mediawiki.org/wiki/API:Query#Title_normalization) + display: + type: string + description: the title as it should be displayed to the user + required: + - canonical + - normalized + - display diff --git a/v1/metadata.yaml b/v1/metadata.yaml index 8bfd76222..555f6a423 100644 --- a/v1/metadata.yaml +++ b/v1/metadata.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki page metadata API description: API for retrieving additional metadata of a given page termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -25,36 +25,34 @@ paths: Gets metadata of a page that's not already covered by the summary endpoint. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Metadata/1.2.0" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean responses: - '200': + 200: description: JSON containing additional metadata of the given page. - schema: - $ref: '#/definitions/metadata' headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Metadata/1.2.0": + schema: + $ref: '#/components/schemas/metadata' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -62,7 +60,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -70,14 +68,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_pcs: request: @@ -88,7 +90,7 @@ paths: return: status: 200 headers: '{{ merge({"cache-control": options.response_cache_control}, - get_from_pcs.headers) }}' + get_from_pcs.headers) }}' body: '{{get_from_pcs.body}}' x-monitor: false @@ -100,188 +102,205 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean +components: + schemas: + metadata: + type: object + properties: + revision: + type: string + description: revision ID for the page + tid: + type: string + description: time UUID for the page/revision + hatnotes: + type: array + description: the hatnotes on the page, with html and plaintext representations + provided for each + items: + $ref: '#/components/schemas/hatnote_or_page_issue' + issues: + type: array + description: the page issues on the page, with html and plaintext representations + provided for each + items: + $ref: '#/components/schemas/hatnote_or_page_issue' + toc: + type: object + description: a table of contents for the page, in structured form + properties: + title: + type: string + description: the TOC title string for the wiki as reported by siteinfo + entries: + type: array + description: section info for the TOC in structured form + items: + $ref: '#/components/schemas/toc_entry' + required: + - title + - entries + language_links: + type: array + description: list of titles and language codes for the article topic on + other language Wikipedias + items: + type: object + description: titles and language codes for the article topic on another + language Wikipedia + properties: + lang: + type: string + description: language code + titles: + type: object + description: titles dictionary + properties: + canonical: + type: string + description: canonical title + normalized: + type: string + description: normalized title + required: + - canonical + - normalized + summary_url: + type: string + description: link to REST API summary + required: + - lang + - titles + - summary_url + categories: + type: array + description: categories the page belongs to + items: + $ref: '#/components/schemas/category' + protection: + type: object + description: info on page edit and move rights + items: + $ref: '#/components/schemas/protection' + description_source: + type: string + enum: + - central + - local + description: Whether the description is defined locally or comes from Wikidata. May + be 'central' or 'local'. + variants: + type: object + properties: {} + required: + - protection + - revision + - tid -# copied from MCS spec.yaml -definitions: + hatnote_or_page_issue: + type: object + properties: + section: + type: integer + description: section ID containing the hatnote or page issue + html: + type: string + description: the hatnote or page issue HTML + required: + - html + - section - metadata: - type: object - properties: - revision: - type: string - description: revision ID for the page - tid: - type: string - description: time UUID for the page/revision - hatnotes: - type: array - description: the hatnotes on the page, with html and plaintext representations provided for each - items: - $ref: '#/definitions/hatnote_or_page_issue' - issues: - type: array - description: the page issues on the page, with html and plaintext representations provided for each - items: - $ref: '#/definitions/hatnote_or_page_issue' - toc: - type: object - description: a table of contents for the page, in structured form - properties: - title: - type: string - description: the TOC title string for the wiki as reported by siteinfo - entries: - type: array - description: section info for the TOC in structured form - items: - $ref: '#/definitions/toc_entry' - required: [ title, entries ] - additionalProperties: false - language_links: - type: array - description: list of titles and language codes for the article topic on other language Wikipedias - items: + toc_entry: + type: object + properties: + level: + type: integer + description: the depth of the heading in the TOC hierarchy + section: + type: integer + description: the position of the section in the order of appearance of all + sections on the page + number: + type: string + description: a numeric representation of the section's position in the page + hierarhcy (e.g., '1', '1.3', '1.3.2') + anchor: + type: string + description: the heading text to be used in constracting a page anchor for + linking + html: + type: string + description: the heading display text (may contain HTML markup) + required: + - anchor + - html + - level + - number + - section + + category: + type: object + properties: + titles: type: object - description: titles and language codes for the article topic on another language Wikipedia + description: titles dictionary properties: - lang: + canonical: + type: string + description: canonical title + normalized: type: string - description: language code - titles: - type: object - description: titles dictionary - properties: - canonical: - type: string - description: canonical title - normalized: - type: string - description: normalized title - required: - - canonical - - normalized - summary_url: + description: normalized title + display: type: string - description: link to REST API summary + description: display title (omitting the "Category:" namespace prefix) required: - - lang - - titles - - summary_url - categories: - type: array - description: categories the page belongs to - items: - $ref: '#/definitions/category' - protection: - type: object - description: info on page edit and move rights - items: - $ref: '#/definitions/protection' - description_source: - type: string - enum: - - central - - local - description: Whether the description is defined locally or comes from Wikidata. May be 'central' or 'local'. - variants: - type: object - required: [ revision, tid, protection ] - additionalProperties: false - - hatnote_or_page_issue: - type: object - properties: - section: - type: integer - description: section ID containing the hatnote or page issue - html: - type: string - description: the hatnote or page issue HTML - required: [ section, html ] - additionalProperties: false - - toc_entry: - type: object - properties: - level: - type: integer - description: the depth of the heading in the TOC hierarchy - section: - type: integer - description: the position of the section in the order of appearance of all sections on the page - number: - type: string - description: a numeric representation of the section's position in the page hierarhcy (e.g., '1', '1.3', '1.3.2') - anchor: - type: string - description: the heading text to be used in constracting a page anchor for linking - html: - type: string - description: the heading display text (may contain HTML markup) - required: [ level, section, number, anchor, html ] - additionalProperties: false + - canonical + - normalized + - display + summary_url: + type: string + description: link to REST API summary + hidden: + type: boolean + description: whether the category is hidden or not + ns: + type: integer + description: the numeric namespace id for the category page + required: + - hidden + - ns + - summary_url + - titles - category: - type: object - properties: - titles: - type: object - description: titles dictionary - properties: - canonical: - type: string - description: canonical title - normalized: + protection: + type: object + properties: + edit: + type: array + description: list of groups with the 'edit' permission + items: type: string - description: normalized title - display: + move: + type: array + description: list of groups with the 'move' permission + items: type: string - description: display title (omitting the "Category:" namespace prefix) - required: - - canonical - - normalized - - display - summary_url: - type: string - description: link to REST API summary - hidden: - type: boolean - description: whether the category is hidden or not - ns: - type: integer - description: the numeric namespace id for the category page - required: [ titles, hidden, summary_url, ns ] - additionalProperties: false - - protection: - type: object - properties: - edit: - type: array - description: list of groups with the 'edit' permission - items: - type: string - move: - type: array - description: list of groups with the 'move' permission - items: - type: string diff --git a/v1/metrics.yaml b/v1/metrics.yaml index c284612a7..18f0ee0fe 100644 --- a/v1/metrics.yaml +++ b/v1/metrics.yaml @@ -1,5 +1,6 @@ +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: Analytics Metrics API description: Analytics Metrics API termsOfService: https://github.com/wikimedia/restbase#restbase @@ -28,69 +29,89 @@ paths: - Rate limit: 100 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path description: | If you want to filter by project, use the domain of any Wikimedia project, for example 'en.wikipedia.org', 'www.mediawiki.org' or 'commons.wikimedia.org'. - type: string required: true + schema: + type: string - name: access in: path description: | If you want to filter by access method, use one of desktop, mobile-app or mobile-web. If you are interested in pageviews regardless of access method, use all-access. - type: string - enum: ['all-access', 'desktop', 'mobile-app', 'mobile-web'] required: true + schema: + type: string + enum: + - all-access + - desktop + - mobile-app + - mobile-web - name: agent in: path description: | If you want to filter by agent type, use one of user, bot or spider. If you are interested in pageviews regardless of agent type, use all-agents. - type: string - enum: ['all-agents', 'user', 'spider', 'bot'] required: true + schema: + type: string + enum: + - all-agents + - user + - spider + - bot - name: article in: path description: | 'The title of any article in the specified project. Any spaces should be replaced with underscores. It also should be URI-encoded, so that non-URI-safe characters like %, / or ? are accepted. Example: Are_You_the_One%3F'. - type: string required: true + schema: + type: string - name: granularity in: path description: | The time unit for the response data. As of today, the only supported granularity for this endpoint is daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path - description: The date of the first day to include, in YYYYMMDD or YYYYMMDDHH format - type: string + description: The date of the first day to include, in YYYYMMDD or YYYYMMDDHH + format required: true + schema: + type: string - name: end in: path - description: The date of the last day to include, in YYYYMMDD or YYYYMMDDHH format - type: string + description: The date of the last day to include, in YYYYMMDD or YYYYMMDDHH + format required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/pageview-article' + content: + application/json: + schema: + $ref: '#/components/schemas/pageview-article' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -122,9 +143,6 @@ paths: - Rate limit: 100 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -132,51 +150,73 @@ paths: If you want to filter by project, use the domain of any Wikimedia project, for example 'en.wikipedia.org', 'www.mediawiki.org' or 'commons.wikimedia.org'. If you are interested in all pageviews regardless of project, use all-projects. - type: string required: true + schema: + type: string - name: access in: path description: | If you want to filter by access method, use one of desktop, mobile-app or mobile-web. If you are interested in pageviews regardless of access method, use all-access. - type: string - enum: ['all-access', 'desktop', 'mobile-app', 'mobile-web'] required: true + schema: + type: string + enum: + - all-access + - desktop + - mobile-app + - mobile-web - name: agent in: path description: | If you want to filter by agent type, use one of user or spider. If you are interested in pageviews regardless of agent type, use all-agents. - type: string - enum: ['all-agents', 'user', 'spider'] required: true + schema: + type: string + enum: + - all-agents + - user + - spider - name: granularity in: path description: | The time unit for the response data. As of today, the supported granularities for this endpoint are hourly, daily, and monthly. - type: string - enum: ['hourly', 'daily', 'monthly'] required: true + schema: + type: string + enum: + - hourly + - daily + - monthly - name: start in: path - description: The timestamp of the first hour/day/month to include, in YYYYMMDDHH format - type: string + description: The timestamp of the first hour/day/month to include, in YYYYMMDDHH + format required: true + schema: + type: string - name: end in: path - description: The timestamp of the last hour/day/month to include, in YYYYMMDDHH format - type: string + description: The timestamp of the last hour/day/month to include, in YYYYMMDDHH + format required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/pageview-project' + content: + application/json: + schema: + $ref: '#/components/schemas/pageview-project' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -230,51 +270,63 @@ paths: - Rate limit: 100 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path description: | If you want to filter by project, use the domain of any Wikimedia project, for example 'en.wikipedia.org', 'www.mediawiki.org' or 'commons.wikimedia.org'. - type: string required: true + schema: + type: string - name: access in: path description: | If you want to filter by access method, use one of desktop, mobile-app or mobile-web. If you are interested in pageviews regardless of access method, use all-access. - type: string - enum: ['all-access', 'desktop', 'mobile-app', 'mobile-web'] required: true + schema: + type: string + enum: + - all-access + - desktop + - mobile-app + - mobile-web - name: year in: path - description: The year of the date for which to retrieve top articles, in YYYY format. - type: string + description: The year of the date for which to retrieve top articles, in YYYY + format. required: true + schema: + type: string - name: month in: path description: | The month of the date for which to retrieve top articles, in MM format. If you want to get the top articles of a whole month, the day parameter should be all-days. - type: string required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top articles, in DD format. - type: string + description: The day of the date for which to retrieve top articles, in DD + format. required: true + schema: + type: string responses: - '200': + 200: description: The list of top articles in the project - schema: - $ref: '#/definitions/pageview-tops' + content: + application/json: + schema: + $ref: '#/components/schemas/pageview-tops' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -305,45 +357,55 @@ paths: - Rate limit: 100 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path description: | If you want to filter by project, use the domain of any Wikimedia project, for example 'en.wikipedia.org', 'www.mediawiki.org' or 'commons.wikimedia.org'. - type: string required: true + schema: + type: string - name: access in: path description: | If you want to filter by access method, use one of desktop, mobile-app or mobile-web. If you are interested in pageviews regardless of access method, use all-access. - type: string - enum: ['all-access', 'desktop', 'mobile-app', 'mobile-web'] required: true + schema: + type: string + enum: + - all-access + - desktop + - mobile-app + - mobile-web - name: year in: path - description: The year of the date for which to retrieve top countries, in YYYY format. - type: string + description: The year of the date for which to retrieve top countries, in + YYYY format. required: true + schema: + type: string - name: month in: path description: | The month of the date for which to retrieve top countries, in MM format. - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of top countries by pageviews in the project - schema: - $ref: '#/definitions/by-country' + content: + application/json: + schema: + $ref: '#/components/schemas/by-country' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -378,52 +440,64 @@ paths: - Rate limit: 100 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path description: | If you want to filter by project, use the domain of any Wikimedia project, for example 'en.wikipedia.org', 'www.mediawiki.org' or 'commons.wikimedia.org'. - type: string required: true + schema: + type: string - name: access-site in: path description: | If you want to filter by accessed site, use one of desktop-site or mobile-site. If you are interested in unique devices regardless of accessed site, use or all-sites. - type: string - enum: ['all-sites', 'desktop-site', 'mobile-site'] required: true + schema: + type: string + enum: + - all-sites + - desktop-site + - mobile-site - name: granularity in: path description: | The time unit for the response data. As of today, the supported granularities for this endpoint are daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path - description: The timestamp of the first day/month to include, in YYYYMMDD format - type: string + description: The timestamp of the first day/month to include, in YYYYMMDD + format required: true + schema: + type: string - name: end in: path description: The timestamp of the last day/month to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/unique-devices' + content: + application/json: + schema: + $ref: '#/components/schemas/unique-devices' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -457,9 +531,6 @@ paths: - Rate limit: 100 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -467,46 +538,62 @@ paths: The name of any Wikimedia project formatted like {language code}.{project name}, for example en.wikipedia. You may pass en.wikipedia.org and the .org will be stripped off. For projects like commons without language codes, use commons.wikimedia. - type: string required: true + schema: + type: string - name: access-site in: path - description: - If you want to filter by access site, use one of desktop-site or mobile-site. - If you are interested in pagecounts regardless of access site use all-sites. - type: string - enum: ['all-sites', 'desktop-site', 'mobile-site'] + description: If you want to filter by access site, use one of desktop-site + or mobile-site. If you are interested in pagecounts regardless of access + site use all-sites. required: true + schema: + type: string + enum: + - all-sites + - desktop-site + - mobile-site - name: granularity in: path description: | The time unit for the response data. As of today, the supported granularities for this endpoint are hourly, daily and monthly. - type: string - enum: ['hourly', 'daily', 'monthly'] required: true + schema: + type: string + enum: + - hourly + - daily + - monthly - name: start in: path - description: The timestamp of the first hour/day/month to include, in YYYYMMDDHH format. - type: string + description: The timestamp of the first hour/day/month to include, in YYYYMMDDHH + format. required: true + schema: + type: string - name: end in: path description: | The timestamp of the last hour/day/month to include, in YYYYMMDDHH format. In hourly and daily granularities this value is inclusive, in the monthly granularity this value is exclusive. - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/pagecounts-project' + content: + application/json: + schema: + $ref: '#/components/schemas/pagecounts-project' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -542,9 +629,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -555,8 +639,9 @@ paths: For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. If you're interested in the aggregation of all projects, use all-projects. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -565,45 +650,64 @@ paths: to the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (new pages in content namespaces) or non-content (new pages in non-content namespaces). If you are interested in new-articles regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: granularity in: path description: | The time unit for the response data. As of today, supported values are daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/new-pages' + content: + application/json: + schema: + $ref: '#/components/schemas/new-pages' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -637,9 +741,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -649,8 +750,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -659,54 +761,79 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edited-pages in content namespaces) or non-content (edited-pages in non-content namespaces). If you are interested in edited-pages regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: activity-level in: path description: | If you want to filter by activity-level, use one of 1..4-edits, 5..24-edits, 25..99-edits or 100..-edits. If you are interested in edited-pages regardless of their activity level, use all-activity-levels. - type: string - enum: ['all-activity-levels', '1..4-edits', '5..24-edits', '25..99-edits', '100..-edits'] required: true + schema: + type: string + enum: + - all-activity-levels + - 1..4-edits + - 5..24-edits + - 25..99-edits + - 100..-edits - name: granularity in: path description: | The time unit for the response data. As of today, supported values are daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/edited-pages' + content: + application/json: + schema: + $ref: '#/components/schemas/edited-pages' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -739,9 +866,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -751,8 +875,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -761,42 +886,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: year in: path - description: The year of the date for which to retrieve top edited-pages, in YYYY format. - type: string + description: The year of the date for which to retrieve top edited-pages, + in YYYY format. required: true + schema: + type: string - name: month in: path - description: The month of the date for which to retrieve top edited-pages, in MM format. If you want to get the top edited-pages of a whole month, the day parameter should be all-days. - type: string + description: The month of the date for which to retrieve top edited-pages, + in MM format. If you want to get the top edited-pages of a whole month, + the day parameter should be all-days. required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top edited-pages, in DD format, or all-days for a monthly value. - type: string + description: The day of the date for which to retrieve top edited-pages, in + DD format, or all-days for a monthly value. required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/top-edited-pages-by-edits' + content: + application/json: + schema: + $ref: '#/components/schemas/top-edited-pages-by-edits' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -828,9 +974,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -840,8 +983,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -850,42 +994,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: year in: path - description: The year of the date for which to retrieve top edited-pages, in YYYY format. - type: string + description: The year of the date for which to retrieve top edited-pages, + in YYYY format. required: true + schema: + type: string - name: month in: path - description: The month of the date for which to retrieve top edited-pages, in MM format. If you want to get the top edited-pages of a whole month, the day parameter should be all-days. - type: string + description: The month of the date for which to retrieve top edited-pages, + in MM format. If you want to get the top edited-pages of a whole month, + the day parameter should be all-days. required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top edited-pages, in DD format, or all-days for a monthly value. - type: string + description: The day of the date for which to retrieve top edited-pages, in + DD format, or all-days for a monthly value. required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/top-edited-pages-by-net-bytes-diff' + content: + application/json: + schema: + $ref: '#/components/schemas/top-edited-pages-by-net-bytes-diff' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -917,9 +1082,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -929,8 +1091,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -939,42 +1102,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: year in: path - description: The year of the date for which to retrieve top edited-pages, in YYYY format. - type: string + description: The year of the date for which to retrieve top edited-pages, + in YYYY format. required: true + schema: + type: string - name: month in: path - description: The month of the date for which to retrieve top edited-pages, in MM format. If you want to get the top edited-pages of a whole month, the day parameter should be all-days. - type: string + description: The month of the date for which to retrieve top edited-pages, + in MM format. If you want to get the top edited-pages of a whole month, + the day parameter should be all-days. required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top edited-pages, in DD format, or all-days for a monthly value. - type: string + description: The day of the date for which to retrieve top edited-pages, in + DD format, or all-days for a monthly value. required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/top-edited-pages-by-abs-bytes-diff' + content: + application/json: + schema: + $ref: '#/components/schemas/top-edited-pages-by-abs-bytes-diff' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1012,9 +1196,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1024,8 +1205,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1034,54 +1216,79 @@ paths: to the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits made in content namespaces) or non-content (edits made in non-content namespaces). If you are interested in editors regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: activity-level in: path description: | If you want to filter by activity-level, use one of 1..4-edits, 5..24-edits, 25..99-edits or 100..-edits. If you are interested in editors regardless of their activity-level, use all-activity-levels. - type: string - enum: ['all-activity-levels', '1..4-edits', '5..24-edits', '25..99-edits', '100..-edits'] required: true + schema: + type: string + enum: + - all-activity-levels + - 1..4-edits + - 5..24-edits + - 25..99-edits + - 100..-edits - name: granularity in: path description: | The time unit for the response data. As of today, supported values are daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/editors' + content: + application/json: + schema: + $ref: '#/components/schemas/editors' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1115,9 +1322,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1127,8 +1331,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1137,42 +1342,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: year in: path - description: The year of the date for which to retrieve top editors, in YYYY format. - type: string + description: The year of the date for which to retrieve top editors, in YYYY + format. required: true + schema: + type: string - name: month in: path - description: The month of the date for which to retrieve top editors, in MM format. If you want to get the top editors of a whole month, the day parameter should be all-days. - type: string + description: The month of the date for which to retrieve top editors, in MM + format. If you want to get the top editors of a whole month, the day parameter + should be all-days. required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top editors, in DD format, or all-days for a monthly value. - type: string + description: The day of the date for which to retrieve top editors, in DD + format, or all-days for a monthly value. required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/top-editors-by-edits' + content: + application/json: + schema: + $ref: '#/components/schemas/top-editors-by-edits' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1206,9 +1432,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1218,8 +1441,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1228,42 +1452,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: year in: path - description: The year of the date for which to retrieve top editors, in YYYY format. - type: string + description: The year of the date for which to retrieve top editors, in YYYY + format. required: true + schema: + type: string - name: month in: path - description: The month of the date for which to retrieve top editors, in MM format. If you want to get the top editors of a whole month, the day parameter should be all-days. - type: string + description: The month of the date for which to retrieve top editors, in MM + format. If you want to get the top editors of a whole month, the day parameter + should be all-days. required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top editors, in DD format, or all-days for a monthly value. - type: string + description: The day of the date for which to retrieve top editors, in DD + format, or all-days for a monthly value. required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/top-editors-by-net-bytes-diff' + content: + application/json: + schema: + $ref: '#/components/schemas/top-editors-by-net-bytes-diff' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1297,9 +1542,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1309,8 +1551,9 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1319,42 +1562,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: year in: path - description: The year of the date for which to retrieve top editors, in YYYY format. - type: string + description: The year of the date for which to retrieve top editors, in YYYY + format. required: true + schema: + type: string - name: month in: path - description: The month of the date for which to retrieve top editors, in MM format. If you want to get the top editors of a whole month, the day parameter should be all-days. - type: string + description: The month of the date for which to retrieve top editors, in MM + format. If you want to get the top editors of a whole month, the day parameter + should be all-days. required: true + schema: + type: string - name: day in: path - description: The day of the date for which to retrieve top editors, in DD format, or all-days for a monthly value. - type: string + description: The day of the date for which to retrieve top editors, in DD + format, or all-days for a monthly value. required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/top-editors-by-abs-bytes-diff' + content: + application/json: + schema: + $ref: '#/components/schemas/top-editors-by-abs-bytes-diff' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1391,9 +1655,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1404,8 +1665,9 @@ paths: For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. If you're interested in the aggregation of all projects, use all-projects. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1414,45 +1676,64 @@ paths: to the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: granularity in: path description: | The time unit for the response data. As of today, supported values are daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/edits' + content: + application/json: + schema: + $ref: '#/components/schemas/edits' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1488,9 +1769,6 @@ paths: - Rate limit: 5 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1500,15 +1778,17 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: page-title in: path description: | The page-title to request edits for. It should be prefixed with canonical namespace. Spaces will be converted to underscores. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1517,35 +1797,50 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: granularity in: path description: | Time unit for the response data. As of today, supported values are daily and monthly - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/edits-per-page' + content: + application/json: + schema: + $ref: '#/components/schemas/edits-per-page' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1674,9 +1969,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1687,35 +1979,45 @@ paths: For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. If you're interested in the aggregation of all projects, use all. - type: string required: true + schema: + type: string - name: granularity in: path description: | The time unit for the response data. As of today, supported values are daily and monthly. - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/new-registered-users' + content: + application/json: + schema: + $ref: '#/components/schemas/new-registered-users' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1741,7 +2043,8 @@ paths: get: tags: - Bytes difference data - summary: Get the sum of net text bytes difference between current edit and previous one. + summary: Get the sum of net text bytes difference between current edit and previous + one. description: | Given a Mediawiki project and a date range, returns a timeseries of bytes difference net sums. You can filter by editors-type (all-editor-types, anonymous, group-bot, name-bot, @@ -1752,9 +2055,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1765,8 +2065,9 @@ paths: projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. If you're interested in the aggregation of all projects, use all-projects. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1775,44 +2076,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: granularity in: path description: | Time unit for the response data. As of today, supported values are daily and monthly - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/net-bytes-difference' + content: + application/json: + schema: + $ref: '#/components/schemas/net-bytes-difference' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -1848,9 +2168,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -1860,15 +2177,17 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: page-title in: path description: | The page-title to request net bytes-difference for. Should be prefixed with the page canonical namespace. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -1877,35 +2196,50 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: granularity in: path description: | Time unit for the response data. As of today, supported values are daily and monthly - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/net-bytes-difference-per-page' + content: + application/json: + schema: + $ref: '#/components/schemas/net-bytes-difference-per-page' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -2036,9 +2370,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -2049,8 +2380,9 @@ paths: projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. If you're interested in the aggregation of all projects, use all-projects. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -2059,44 +2391,63 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: page-type in: path description: | If you want to filter by page-type, use one of content (edits on pages in content namespaces) or non-content (edits on pages in non-content namespaces). If you are interested in edits regardless of their page-type, use all-page-types. - type: string - enum: ['all-page-types', 'content', 'non-content'] required: true + schema: + type: string + enum: + - all-page-types + - content + - non-content - name: granularity in: path description: | Time unit for the response data. As of today, supported values are daily and monthly - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/absolute-bytes-difference' + content: + application/json: + schema: + $ref: '#/components/schemas/absolute-bytes-difference' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -2132,9 +2483,6 @@ paths: - Rate limit: 25 req/s - License: Data accessible via this endpoint is available under the [CC0 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/). - produces: - - application/json - - application/problem+json parameters: - name: project in: path @@ -2144,15 +2492,17 @@ paths: off. For projects like commons without language codes, use commons.wikimedia. For projects like www.mediawiki.org, you can use that full string, or just use mediawiki or mediawiki.org. - type: string required: true + schema: + type: string - name: page-title in: path description: | The page-title to request absolute bytes-difference for. Should be prefixed with the page canonical namespace. - type: string required: true + schema: + type: string - name: editor-type in: path description: | @@ -2161,35 +2511,50 @@ paths: the bot group but having bot-like names) or user (registered account not in bot group nor having bot-like name). If you are interested in edits regardless of their editor-type, use all-editor-types. - type: string - enum: ['all-editor-types', 'anonymous', 'group-bot', 'name-bot', 'user'] required: true + schema: + type: string + enum: + - all-editor-types + - anonymous + - group-bot + - name-bot + - user - name: granularity in: path description: | Time unit for the response data. As of today, supported values are daily and monthly - type: string - enum: ['daily', 'monthly'] required: true + schema: + type: string + enum: + - daily + - monthly - name: start in: path description: The date of the first day to include, in YYYYMMDD format - type: string required: true + schema: + type: string - name: end in: path description: The date of the last day to include, in YYYYMMDD format - type: string required: true + schema: + type: string responses: - '200': + 200: description: The list of values - schema: - $ref: '#/definitions/absolute-bytes-difference-per-page' + content: + application/json: + schema: + $ref: '#/components/schemas/absolute-bytes-difference-per-page' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -2301,668 +2666,746 @@ paths: ######################################## -# Definitions +# Components ######################################## -definitions: - listing: - description: The result format for listings - required: - - items - properties: - items: - type: array +components: + schemas: + listing: + description: The result format for listings + required: + - items + type: object + properties: items: - type: string + type: array + items: + type: string - pageview-article: - properties: - items: - type: array + pageview-article: + type: object + properties: items: - properties: - project: - type : string - access: - type : string - article: - type: string - agent: - type: string - granularity: - type: string - timestamp: - # the hourly timestamp will be stored as YYYYMMDDHH - type: string - views: - type: integer - format: int64 - - pageview-project: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + access: + type: string + article: + type: string + agent: + type: string + granularity: + type: string + timestamp: + type: string + views: + type: integer + format: int64 + + pageview-project: + type: object + properties: items: - properties: - project: - type : string - access: - type : string - agent: - type: string - granularity: - type: string - timestamp: - # the hourly timestamp will be stored as YYYYMMDDHH - type: string - views: - type: integer - format: int64 - - pageview-tops: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + access: + type: string + agent: + type: string + granularity: + type: string + timestamp: + # the hourly timestamp will be stored as YYYYMMDDHH + type: string + views: + type: integer + format: int64 + + pageview-tops: + type: object + properties: items: - properties: - project: - type: string - access: - type : string - year: - type: string - month: - type: string - day: - type: string - articles: - type: array - items: - properties: - rank: - type: integer - format: int32 - article: - type: string - views: - type: integer - format: int64 - - - by-country: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + access: + type: string + year: + type: string + month: + type: string + day: + type: string + articles: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + article: + type: string + views: + type: integer + format: int64 + + by-country: + type: object + properties: items: - properties: - project: - type: string - access: - type : string - year: - type: string - month: - type: string - countries: - type: array - items: - properties: - rank: - type: integer - format: int32 - country: - type: string - views: - type: integer - format: int64 - - unique-devices: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + access: + type: string + year: + type: string + month: + type: string + countries: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + country: + type: string + views: + type: integer + format: int64 + + unique-devices: + type: object + properties: items: - properties: - project: - type : string - access-site: - type : string - granularity: - type: string - timestamp: - # the daily timestamp will be stored as YYYYMMDD - type: string - devices: - type: integer - format: int64 - - pagecounts-project: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + access-site: + type: string + granularity: + type: string + timestamp: + # the daily timestamp will be stored as YYYYMMDD + type: string + devices: + type: integer + format: int64 + + pagecounts-project: + type: object + properties: items: - properties: - project: - type : string - access-site: - type : string - granularity: - type: string - timestamp: - type: string - count: - type: integer - format: int64 - - ## Edited Pages - new-pages: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + access-site: + type: string + granularity: + type: string + timestamp: + type: string + count: + type: integer + format: int64 + + ## Edited Pages + new-pages: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - new_pages: - type: integer - format: int32 - - edited-pages: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + new_pages: + type: integer + format: int32 + + edited-pages: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - activity-level: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - edited_pages: - type: integer - format: int32 - - top-edited-pages-by-edits: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + activity-level: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + edited_pages: + type: integer + format: int32 + + top-edited-pages-by-edits: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - top: - type: array - items: - properties: - rank: - type: integer - format: int32 - page_title: - type: string - edits: - type: integer - format: int64 - - top-edited-pages-by-net-bytes-diff: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + top: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + page_title: + type: string + edits: + type: integer + format: int64 + + top-edited-pages-by-net-bytes-diff: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - top: - type: array - items: - properties: - rank: - type: integer - format: int32 - page_title: - type: string - net_bytes_diff: - type: integer - format: int64 - - top-edited-pages-by-abs-bytes-diff: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + top: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + page_title: + type: string + net_bytes_diff: + type: integer + format: int64 + + top-edited-pages-by-abs-bytes-diff: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - top: - type: array - items: - properties: - rank: - type: integer - format: int32 - page_title: - type: string - abs_bytes_diff: - type: integer - format: int64 - - ## Editors - editors: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + top: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + page_title: + type: string + abs_bytes_diff: + type: integer + format: int64 + + ## Editors + editors: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - activity-level: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - editors: - type: integer - format: int32 - - top-editors-by-edits: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + activity-level: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + editors: + type: integer + format: int32 + + top-editors-by-edits: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - top: - type: array - items: - properties: - rank: - type: integer - format: int32 - user_text: - type: string - edits: - type: integer - format: int64 - - top-editors-by-net-bytes-diff: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + top: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + user_text: + type: string + edits: + type: integer + format: int64 + + top-editors-by-net-bytes-diff: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - top: - type: array - items: - properties: - rank: - type: integer - format: int32 - user_text: - type: string - net_bytes_diff: - type: integer - format: int64 - - top-editors-by-abs-bytes-diff: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + top: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + user_text: + type: string + net_bytes_diff: + type: integer + format: int64 + + top-editors-by-abs-bytes-diff: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - top: - type: array - items: - properties: - rank: - type: integer - format: int32 - user_text: - type: string - abs_bytes_diff: - type: integer - format: int64 - - ## Edits - edits: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + top: + type: array + items: + type: object + properties: + rank: + type: integer + format: int32 + user_text: + type: string + abs_bytes_diff: + type: integer + format: int64 + + ## Edits + edits: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type : string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - edits: - type: integer - format: int64 - - edits-per-page: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + edits: + type: integer + format: int64 + + edits-per-page: + type: object + properties: items: - properties: - project: - type : string - page-title: - type: string - editor-type: - type : string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - edits: - type: integer - format: int64 - - edits-per-editor: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + page-title: + type: string + editor-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + edits: + type: integer + format: int64 + + edits-per-editor: + type: object + properties: items: - properties: - project: - type : string - user-text: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - edits: - type: integer - format: int64 - - ## New Registered Users - new-registered-users: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + user-text: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + edits: + type: integer + format: int64 + + ## New Registered Users + new-registered-users: + type: object + properties: items: - properties: - project: - type : string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - new_registered_users: - type: integer - format: int32 - - ## Net Bytes Difference - net-bytes-difference: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + new_registered_users: + type: integer + format: int32 + + ## Net Bytes Difference + net-bytes-difference: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type : string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - net_bytes_diff: - type: integer - format: int64 - - net-bytes-difference-per-page: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + net_bytes_diff: + type: integer + format: int64 + + net-bytes-difference-per-page: + type: object + properties: items: - properties: - project: - type : string - page-title: - type: string - editor-type: - type : string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - net_bytes_diff: - type: integer - format: int64 - - net-bytes-difference-per-editor: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + page-title: + type: string + editor-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + net_bytes_diff: + type: integer + format: int64 + + net-bytes-difference-per-editor: + type: object + properties: items: - properties: - project: - type : string - user-text: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - net_bytes_diff: - type: integer - format: int64 - - ## Net Bytes Difference - absolute-bytes-difference: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + user-text: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + net_bytes_diff: + type: integer + format: int64 + + ## Net Bytes Difference + absolute-bytes-difference: + type: object + properties: items: - properties: - project: - type : string - editor-type: - type : string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - abs_bytes_diff: - type: integer - format: int64 - absolute-bytes-difference-per-page: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + editor-type: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + abs_bytes_diff: + type: integer + format: int64 + + absolute-bytes-difference-per-page: + type: object + properties: items: - properties: - project: - type : string - page-title: - type: string - editor-type: - type : string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - abs_bytes_diff: - type: integer - format: int64 - - absolute-bytes-difference-per-editor: - properties: - items: - type: array + type: array + items: + type: object + properties: + project: + type: string + page-title: + type: string + editor-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + abs_bytes_diff: + type: integer + format: int64 + + absolute-bytes-difference-per-editor: + type: object + properties: items: - properties: - project: - type : string - user-text: - type: string - page-type: - type: string - granularity: - type: string - results: - type: array - items: - properties: - timestamp: - type: string - abs_bytes_diff: - type: integer - format: int64 + type: array + items: + type: object + properties: + project: + type: string + user-text: + type: string + page-type: + type: string + granularity: + type: string + results: + type: array + items: + type: object + properties: + timestamp: + type: string + abs_bytes_diff: + type: integer + format: int64 diff --git a/v1/mobile-html.yaml b/v1/mobile-html.yaml index 5be6fa1f6..b07ac9c00 100644 --- a/v1/mobile-html.yaml +++ b/v1/mobile-html.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki page mobile-html API description: API for retrieving page content for reading purposes termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -53,34 +53,34 @@ paths: * FooterTransformer: seems to be more UI than content, requires I18N, too Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Mobile-HTML/1.0.0" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean responses: - '200': + 200: description: mobile-optimized HTML of the given page. headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Mobile-HTML/1.0.0": + schema: + type: string + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -88,7 +88,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -96,14 +96,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_pcs: request: @@ -114,7 +118,7 @@ paths: return: status: 200 headers: '{{ merge({"cache-control": options.response_cache_control}, - get_from_pcs.headers) }}' + get_from_pcs.headers) }}' body: '{{get_from_pcs.body}}' x-monitor: false @@ -126,22 +130,21 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean diff --git a/v1/mobileapps.yaml b/v1/mobileapps.yaml index 1b4966d4a..95573a08c 100644 --- a/v1/mobileapps.yaml +++ b/v1/mobileapps.yaml @@ -19,44 +19,42 @@ paths: native mobile applications. Note that the output is split by sections. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/mobile-sections/0.14.1" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string - responses: - '200': - description: JSON containing HTML sections and metadata for the given page title. + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. schema: - type: object - # FIXME! + type: string + responses: + 200: + description: JSON containing HTML sections and metadata for the given page + title. + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/mobile-sections/0.14.1": + schema: + type: object + # FIXME! headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -64,7 +62,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -72,14 +70,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - from_backend: request: @@ -91,7 +93,7 @@ paths: return: status: '{{from_backend.status}}' headers: '{{ merge({"cache-control": options.response_cache_control}, - from_backend.headers) }}' + from_backend.headers) }}' body: '{{from_backend.body}}' x-monitor: true x-amples: @@ -116,32 +118,30 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string x-request-handler: - from_backend: request: @@ -153,7 +153,7 @@ paths: return: status: '{{from_backend.status}}' headers: '{{ merge({"cache-control": options.response_cache_control}, - from_backend.headers) }}' + from_backend.headers) }}' body: '{{from_backend.body}}' x-monitor: false @@ -172,44 +172,41 @@ paths: for viewing with native mobile applications. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/mobile-sections/0.14.1" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string responses: - '200': + 200: description: The HTML for the given page title. - schema: - type: object - # FIXME! + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/mobile-sections/0.14.1": + schema: + type: object + # FIXME! headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -217,7 +214,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -225,14 +222,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - from_backend: request: @@ -244,7 +245,7 @@ paths: return: status: '{{from_backend.status}}' headers: '{{ merge({"cache-control": options.response_cache_control}, - from_backend.headers) }}' + from_backend.headers) }}' body: '{{from_backend.body}}' x-monitor: false @@ -256,32 +257,30 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string x-request-handler: - from_backend: request: @@ -293,7 +292,7 @@ paths: return: status: '{{from_backend.status}}' headers: '{{ merge({"cache-control": options.response_cache_control}, - from_backend.headers) }}' + from_backend.headers) }}' body: '{{from_backend.body}}' /mobile-sections-remaining/{title}: @@ -312,44 +311,41 @@ paths: provided as a JSON object containing the sections. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/mobile-sections/0.14.1" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string responses: - '200': + 200: description: JSON wrapping HTML sections for the given page title. - schema: - type: object - # FIXME! + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/mobile-sections/0.14.1": + schema: + type: object + # FIXME! headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -357,7 +353,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -365,14 +361,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - from_backend: request: @@ -384,7 +384,7 @@ paths: return: status: '{{from_backend.status}}' headers: '{{ merge({"cache-control": options.response_cache_control}, - from_backend.headers) }}' + from_backend.headers) }}' body: '{{from_backend.body}}' x-monitor: false @@ -396,32 +396,30 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string x-request-handler: - from_backend: request: @@ -433,5 +431,5 @@ paths: return: status: '{{from_backend.status}}' headers: '{{ merge({"cache-control": options.response_cache_control}, - from_backend.headers) }}' + from_backend.headers) }}' body: '{{from_backend.body}}' diff --git a/v1/onthisday.yaml b/v1/onthisday.yaml index 9eec5db85..b90b77d02 100644 --- a/v1/onthisday.yaml +++ b/v1/onthisday.yaml @@ -17,49 +17,57 @@ paths: - Events: a list of significant events which happened on the provided day and month and which are not covered by the other types yet Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/onthisday/0.3.3" - - application/problem+json parameters: - name: type in: path - description: 'Type of events' - type: string + description: Type of events required: true - enum: - - all - - selected - - births - - deaths - - events - - holidays + schema: + type: string + enum: + - all + - selected + - births + - deaths + - events + - holidays - name: mm in: path - description: 'Month events are requested for, 0-padded' - type: string + description: Month events are requested for, 0-padded required: true + schema: + type: string - name: dd in: path - description: 'Day of the month events are requested for, 0-padded' - type: string + description: Day of the month events are requested for, 0-padded required: true + schema: + type: string responses: - '200': + 200: description: JSON containing all of the featured content - schema: - $ref: '#/definitions/onthisdayResponse' - '404': + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/onthisday/0.3.3": + schema: + $ref: '#/components/schemas/onthisdayResponse' + 404: description: No data found for the requested date - schema: - $ref: '#/definitions/problem' - '501': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 501: description: Unsupported language - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' operationId: onThisDay x-monitor: false # TODO: the check has been disabled due to RB deployment @@ -103,38 +111,33 @@ paths: # pages: # - title: /.+/ -definitions: - onthisday: - type: array - items: +components: + schemas: + onthisday: + type: array + items: + type: object + properties: + text: + type: string + description: Short description of the event + pages: + type: array + description: List of pages related to the event + items: + $ref: '#/components/schemas/summary' + + onthisdayResponse: type: object + description: Lists of events which happened on the provided day and month properties: - text: - type: string - description: Short description of the event - pages: - type: array - description: List of pages related to the event - items: - $ref: '#/definitions/summary' - - onthisdayResponse: - type: object - description: Lists of events which happened on the provided day and month - properties: - births: - description: A list of birthdays which happened on the provided day and month - $ref: '#/definitions/onthisday' - deaths: - description: A list of deaths which happened on the provided day and month - $ref: '#/definitions/onthisday' - events: - description: A list of significant events which happened on the provided day and month and which are not covered by the other types yet - $ref: '#/definitions/onthisday' - holidays: - description: A list of fixed holidays celebrated on the provided day and month - $ref: '#/definitions/onthisday' - selected: - description: A list of a few selected anniversaries which occur on the provided day and month; often the entries are curated for the current year - $ref: '#/definitions/onthisday' - additionalProperties: false + births: + $ref: '#/components/schemas/onthisday' + deaths: + $ref: '#/components/schemas/onthisday' + events: + $ref: '#/components/schemas/onthisday' + holidays: + $ref: '#/components/schemas/onthisday' + selected: + $ref: '#/components/schemas/onthisday' diff --git a/v1/pdf.yaml b/v1/pdf.yaml index adc03ceec..ebbd1c33b 100644 --- a/v1/pdf.yaml +++ b/v1/pdf.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki PDF API description: Page PDF Render API termsOfService: https://github.com/wikimedia/restbase#restbase @@ -25,35 +25,40 @@ paths: Renders the page content as PDF. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/pdf - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string responses: - '200': + 200: description: The PDF render of an article - schema: - type: file headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '404': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + application/pdf: + schema: + type: string + format: binary + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - operationId: 'generatePDF' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + operationId: generatePDF # x-request-handler: # - get_latest_revision: # request: diff --git a/v1/random.yaml b/v1/random.yaml index a20dbd0bc..c78ca702a 100644 --- a/v1/random.yaml +++ b/v1/random.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 paths: /random/{format}: get: @@ -9,29 +9,33 @@ paths: Redirects the client to the URI for the desired format for a random page title. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Random/0.6.0" - - application/problem+json parameters: - name: format in: path description: The desired return format - type: string - enum: - - title - - html - - summary - - related - - mobile-sections - - mobile-sections-lead required: true + schema: + type: string + enum: + - title + - html + - summary + - related + - mobile-sections + - mobile-sections-lead responses: - '303': + 303: description: The redirect to the desired format URI for a random page + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Random/0.6.0": + schema: + type: object default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - title_from_mobileapps: request: @@ -40,6 +44,5 @@ paths: status: 303 headers: cache_control: '{{options.random_cache_control}}' - location: '../{request.params.format}/{title_from_mobileapps.body.items[0].title}' + location: ../{request.params.format}/{title_from_mobileapps.body.items[0].title} x-monitor: false - diff --git a/v1/recommend.yaml b/v1/recommend.yaml index e960f5210..305329c86 100644 --- a/v1/recommend.yaml +++ b/v1/recommend.yaml @@ -1,5 +1,5 @@ info: - version: '1.0.0' + version: 1.0.0 title: Recommendation API description: Recommendation API termsOfService: https://github.com/wikimedia/restbase @@ -22,30 +22,32 @@ paths: See more at [Recommendation API documentation](https://meta.wikimedia.org/wiki/Recommendation_API) Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: from_lang in: path description: The source language code - type: string required: true + schema: + type: string - name: count in: query description: The max number of articles to return - type: integer - required: false - default: 24 + schema: + type: integer + default: 24 responses: - '200': + 200: description: the list of articles recommended for translation - schema: - $ref: '#/definitions/recommendation_result' + content: + application/json: + schema: + $ref: '#/components/schemas/recommendation_result' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: @@ -59,19 +61,21 @@ paths: - name: from_lang in: path description: The source language code - type: string required: true + schema: + type: string - name: seed_article in: path description: The article to use as a search seed - type: string required: true + schema: + type: string - name: count in: query description: The max number of articles to return - type: integer - required: false - default: 24 + schema: + type: integer + default: 24 /recommendation/article/creation/morelike/{seed_article}: x-route-filters: @@ -90,60 +94,67 @@ paths: from the domain language Wikipedia. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: seed_article in: path description: The article title used to search similar but missing articles - type: string required: true - responses: - '200': - description: the prioritized list of Wikidata IDs recommended for creation as Wikipedia articles schema: - $ref: '#/definitions/morelike_result' + type: string + responses: + 200: + description: the prioritized list of Wikidata IDs recommended for creation + as Wikipedia articles + content: + application/json: + schema: + $ref: '#/components/schemas/morelike_result' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_backend: request: uri: '{{options.host}}/{{domain}}/v1/article/creation/morelike/{seed_article}' x-monitor: false -definitions: - recommendation_result: - type: object - properties: - count: - type: integer - description: the number of recommendations returned - items: - type: array - description: the list of articles recommended for translation - items: - type: object - properties: - wikidata_id: - type: string - description: wikidata id for the item - title: - type: string - description: title of the article in the source language - sitelink_count: - type: integer - description: count of sites the wikidata item is linked to - morelike_result: - type: array - description: the prioritized list of Wikidata IDs recommended for creation as Wikipedia articles - items: + +components: + schemas: + recommendation_result: type: object properties: - wikidata_id: - type: string - description: Wikidata ID for the item - score: - type: number - description: Score of the recommendation. The higher the score, the more important the recommendation is. + count: + type: integer + description: the number of recommendations returned + items: + type: array + description: the list of articles recommended for translation + items: + type: object + properties: + wikidata_id: + type: string + description: wikidata id for the item + title: + type: string + description: title of the article in the source language + sitelink_count: + type: integer + description: count of sites the wikidata item is linked to + morelike_result: + type: array + description: the prioritized list of Wikidata IDs recommended for creation as + Wikipedia articles + items: + type: object + properties: + wikidata_id: + type: string + description: Wikidata ID for the item + score: + type: number + description: Score of the recommendation. The higher the score, the more + important the recommendation is. diff --git a/v1/references.yaml b/v1/references.yaml index 196aa8c05..50821404f 100644 --- a/v1/references.yaml +++ b/v1/references.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki page references API description: API for retrieving references of a given page termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions @@ -26,36 +26,34 @@ paths: and allow some reference lists to be rebuild. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/References/1.0.0" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean responses: - '200': + 200: description: JSON containing a structure of references on the given page. - schema: - $ref: '#/definitions/references_response' headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/References/1.0.0": + schema: + $ref: '#/components/schemas/references_response' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -63,7 +61,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -71,14 +69,18 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-request-handler: - get_from_pcs: request: @@ -89,7 +91,7 @@ paths: return: status: 200 headers: '{{ merge({"cache-control": options.response_cache_control}, - get_from_pcs.headers) }}' + get_from_pcs.headers) }}' body: '{{get_from_pcs.body}}' x-monitor: false @@ -101,134 +103,132 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path - description: > - Optional page revision. Note that older revisions are not stored, so - request latency with the revision would be higher. - type: integer + description: | + Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher. required: true + schema: + type: integer - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean # copied from MCS spec.yaml -definitions: - - references_response: - type: object - description: Reference lists and references - properties: - revision: - type: string - description: revision ID for the page - tid: - type: string - description: time UUID for the page/revision - reference_lists: - $ref: '#/definitions/reference_lists' - references_by_id: - $ref: '#/definitions/references_by_id' - additionalProperties: false - required: - - revision - - tid - - reference_lists - - references_by_id - - reference_lists: - type: array - description: A list of reference lists - items: - $ref: '#/definitions/reference_list' - - reference_list: - type: object - description: A single reference list - properties: - id: - type: ['string', 'null'] - description: Identifier for the whole reference list. May be null. - section_heading: - type: object - description: | - Object containing information about the section heading this reference list - is shown in. - properties: - id: - type: string - description: Identifier for the section, which can be used to link to it - html: - type: string - description: HTML content of section heading - order: - type: array - description: | - List of identifiers for individual references, which can be used to lookup - the reference details in references_by_id. - items: +components: + schemas: + references_response: + type: object + description: Reference lists and references + properties: + revision: + type: string + description: revision ID for the page + tid: type: string - additionalProperties: false - required: - - id - - order + description: time UUID for the page/revision + reference_lists: + $ref: '#/components/schemas/reference_lists' + references_by_id: + $ref: '#/components/schemas/references_by_id' + required: + - revision + - tid + - reference_lists + - references_by_id - references_by_id: - type: object - description: A map of reference ids to reference details - properties: - default: - $ref: '#/definitions/reference_detail_item' + reference_lists: + type: array + description: A list of reference lists + items: + $ref: '#/components/schemas/reference_list' - reference_detail_item: - type: object - description: Information about one reference - properties: - back_links: - type: array - description: A list of back links, can be empty in rare cases - items: - $ref: '#/definitions/reference_detail_item_back_link' - content: - type: object - properties: - html: - type: string - description: HTML representation of the reference content - type: + reference_list: + type: object + description: A single reference list + properties: + id: + type: string + nullable: true + description: Identifier for the whole reference list. May be null. + section_heading: + type: object + description: | + Object containing information about the section heading this reference list + is shown in. + properties: + id: + type: string + description: Identifier for the section, which can be used to link to + it + html: + type: string + description: HTML content of section heading + order: + type: array + description: | + List of identifiers for individual references, which can be used to lookup + the reference details in references_by_id. + items: type: string - enum: - - generic - - book - - journal - - news - - web - description: Known citation type if there is exactly one cite tag, else 'generic' - additionalProperties: false + required: + - id + - order - reference_detail_item_back_link: - type: object - description: Information about one link back to where on the page a given reference was used - properties: - href: - type: string - description: Relative URL pointing to anchor on same page - text: - type: string - description: | - Either an arrow for a single back link or another (usually single) chararacter - to distinguish multiple back links. - additionalProperties: false - required: - - href - - text + references_by_id: + type: object + description: A map of reference ids to reference details + properties: + default: + $ref: '#/components/schemas/reference_detail_item' + reference_detail_item: + type: object + description: Information about one reference + properties: + back_links: + type: array + description: A list of back links, can be empty in rare cases + items: + $ref: '#/components/schemas/reference_detail_item_back_link' + content: + type: object + properties: + html: + type: string + description: HTML representation of the reference content + type: + type: string + enum: + - generic + - book + - journal + - news + - web + description: Known citation type if there is exactly one cite tag, else + 'generic' + + reference_detail_item_back_link: + type: object + description: Information about one link back to where on the page a given reference + was used + properties: + href: + type: string + description: Relative URL pointing to anchor on same page + text: + type: string + description: | + Either an arrow for a single back link or another (usually single) chararacter + to distinguish multiple back links. + required: + - href + - text diff --git a/v1/related.yaml b/v1/related.yaml index c408f04ca..584b0c03e 100644 --- a/v1/related.yaml +++ b/v1/related.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki Related Pages API description: Related pages API termsOfService: https://github.com/wikimedia/restbase#restbase @@ -23,36 +23,41 @@ paths: and a thumbnail. Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - produces: - - application/json - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string responses: - '200': + 200: description: The related pages - schema: - $ref: '#/definitions/related' - '404': + content: + application/json: + schema: + $ref: '#/components/schemas/related' + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' operationId: getRelatedPages x-monitor: false -definitions: - related: - type: object - properties: - pages: - type: array - items: - $ref: '#/definitions/summary' +components: + schemas: + related: + type: object + properties: + pages: + type: array + items: + $ref: '#/components/schemas/summary' diff --git a/v1/summary.yaml b/v1/summary.yaml index 358c518e9..708ef5729 100644 --- a/v1/summary.yaml +++ b/v1/summary.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki Summary API description: Page content summary API termsOfService: https://github.com/wikimedia/restbase#restbase @@ -27,43 +27,40 @@ paths: the page. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.2.0" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string responses: - '200': + 200: description: The summary for the given page - schema: - $ref: '#/definitions/summary' headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.2.0": + schema: + $ref: '#/components/schemas/summary' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -71,7 +68,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -79,23 +76,25 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-setup-handler: # Set up a simple key-value bucket. - init: - method: 'put' + method: put uri: /{domain}/sys/key_value/page_summary body: - valueType: 'json' - + valueType: json x-request-handler: - storage: request: @@ -107,7 +106,7 @@ paths: status: 404 return_if: # Typical case: Return straight from storage. - status: '2xx' + status: 2xx return: status: 200 headers: @@ -165,9 +164,13 @@ paths: # handler completely, and avoid issuing purges. # Also if we didn't really store anything, return as well. catch: - status: [ 202, 412 ] + status: + - 202 + - 412 return_if: - status: [ 202, 412 ] + status: + - 202 + - 412 return: status: 200 headers: @@ -179,7 +182,7 @@ paths: request: method: post headers: - 'cache-control': '{{request.headers.cache-control}}' + cache-control: '{{request.headers.cache-control}}' uri: /{domain}/sys/events/ body: - meta: diff --git a/v1/summary_new.yaml b/v1/summary_new.yaml index 3b62427b9..6379ab879 100644 --- a/v1/summary_new.yaml +++ b/v1/summary_new.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki Summary API description: Page content summary API termsOfService: https://github.com/wikimedia/restbase#restbase @@ -29,43 +29,40 @@ paths: the page. Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable) - produces: - - application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.3.7" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: redirect in: query - description: > - Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) - return HTTP 302 with a redirect target in `Location` header and content in the body. - + description: | + Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body. To get a 200 response instead, supply `false` to the `redirect` parameter. - type: boolean - required: false + schema: + type: boolean - name: Accept-Language in: header - description: > - The desired language variant code for wikis where LanguageConverter is enabled. - Example: `sr-el` for Latin transcription of the Serbian language. - required: false - type: string + description: | + The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language. + schema: + type: string responses: - '200': + 200: description: The summary for the given page - schema: - $ref: '#/definitions/summary' headers: ETag: - type: string - description: > - Syntax: "{revision}/{tid}". - Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" - '301': + description: | + Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc" + schema: + type: string + content: + application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.3.7": + schema: + $ref: '#/components/schemas/summary' + 301: description: | A permanent redirect is returned if the supplied article title was not in the normalized form. To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform @@ -73,7 +70,7 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '302': + 302: description: | The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects). The `location` header points to the redirect target. @@ -81,23 +78,25 @@ paths: Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`) will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204). - '404': + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-setup-handler: # Set up a simple key-value bucket. - init: - method: 'put' + method: put uri: /{domain}/sys/key_value/page_summary body: - valueType: 'json' - + valueType: json x-request-handler: - storage: request: @@ -109,7 +108,7 @@ paths: status: 404 return_if: # Typical case: Return straight from storage. - status: '2xx' + status: 2xx return: status: 200 headers: @@ -148,9 +147,13 @@ paths: # handler completely, and avoid issuing purges. # Also don't emit an event if nothing new was actually stored (code 202) catch: - status: [ 202, 412 ] + status: + - 202 + - 412 return_if: - status: [ 202, 412 ] + status: + - 202 + - 412 return: status: 200 headers: diff --git a/v1/transform-global.yaml b/v1/transform-global.yaml index b5d2ef668..b65bf3e8f 100644 --- a/v1/transform-global.yaml +++ b/v1/transform-global.yaml @@ -1,5 +1,6 @@ +openapi: 3.0.1 info: - version: '1.0.0' + version: 1.0.0 title: Global Transform API description: Global Transform API termsOfService: https://github.com/wikimedia/restbase @@ -9,44 +10,52 @@ info: paths: /html/from/{from_lang}/to/{to_lang}: post: &html_from_lang_to_lang_post_spec - tags: ['Transform'] + tags: + - Transform summary: Machine-translate content description: | Fetches the machine translation for the posted content from the source to the destination language. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - consumes: - - application/x-www-form-urlencoded - produces: - - application/json - - application/problem+json parameters: - name: from_lang in: path description: The source language code - type: string required: true + schema: + type: string - name: to_lang in: path description: The target language code - type: string - required: true - - name: html - in: formData - description: The HTML content to translate - type: string required: true - x-textarea: true + schema: + type: string + requestBody: + content: + application/x-www-form-urlencoded: + schema: + required: + - html + properties: + html: + type: string + description: The HTML content to translate + x-textarea: true + required: true responses: - '200': + 200: description: The translated content - schema: - $ref: '#/definitions/cx_mt' + content: + application/json: + schema: + $ref: '#/components/schemas/cx_mt' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false x-request-handler: - get_from_cx: @@ -63,66 +72,80 @@ paths: - name: from_lang in: path description: The source language code - type: string required: true + schema: + type: string - name: to_lang in: path description: The target language code - type: string required: true + schema: + type: string - name: provider in: path description: The machine translation provider id - type: string - required: true - enum: - - Apertium - - Yandex - - Youdao - - name: html - in: formData - description: The HTML content to translate - type: string required: true - x-textarea: true + schema: + type: string + enum: + - Apertium + - Yandex + - Youdao + requestBody: + content: + multipart/form-data: + schema: + required: + - html + properties: + html: + type: string + description: The HTML content to translate + x-textarea: true + required: true /word/from/{from_lang}/to/{to_lang}/{word}: get: &word_from_lang_to_lang_word_get_spec - tags: ['Transform'] + tags: + - Transform summary: Fetch the dictionary meaning of a word description: | Fetches the dictionary meaning of a word from a language and displays it in the target language. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: from_lang in: path description: The source language code - type: string required: true + schema: + type: string - name: to_lang in: path description: The target language code - type: string required: true + schema: + type: string - name: word in: path description: The word to lookup - type: string required: true + schema: + type: string responses: - '200': + 200: description: the dictionary translation for the given word - schema: - $ref: '#/definitions/cx_dict' + content: + application/json: + schema: + $ref: '#/components/schemas/cx_dict' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false x-request-handler: - get_from_cx: @@ -136,58 +159,66 @@ paths: - name: from_lang in: path description: The source language code - type: string required: true + schema: + type: string - name: to_lang in: path description: The target language code - type: string required: true + schema: + type: string - name: word in: path description: The word to lookup - type: string required: true + schema: + type: string - name: provider in: path description: The dictionary provider id - type: string required: true - enum: - - JsonDict - - Dictd + schema: + type: string + enum: + - JsonDict + - Dictd /list/pair/{from}/{to}/: get: - tags: ['Transform'] + tags: + - Transform summary: Lists the tools available for a language pair description: | Fetches the list of tools that are available for the given pair of languages. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: from in: path description: The source language code - type: string required: true + schema: + type: string - name: to in: path description: The target language code - type: string required: true + schema: + type: string responses: - '200': + 200: description: the list of tools available for the language pair - schema: - $ref: '#/definitions/cx_list_tools' + content: + application/json: + schema: + $ref: '#/components/schemas/cx_list_tools' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false x-request-handler: - get_from_cx: @@ -195,33 +226,37 @@ paths: uri: '{{options.cx_host}}/v1/list/pair/{from}/{to}' /list/tool/{tool}: get: &list_tool_tool_get_spec - tags: ['Transform'] + tags: + - Transform summary: Lists the tools and language pairs available for the given tool category description: | Fetches the list of tools and all of the language pairs it can translate Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: tool in: path description: The tool category to list tools and language pairs for - type: string required: true - enum: - - mt - - dictionary - responses: - '200': - description: the list of language pairs available for a given translation tool schema: - $ref: '#/definitions/cx_list_pairs_for_tool' + type: string + enum: + - mt + - dictionary + responses: + 200: + description: the list of language pairs available for a given translation + tool + content: + application/json: + schema: + $ref: '#/components/schemas/cx_list_pairs_for_tool' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false x-request-handler: - get_from_cx: @@ -235,21 +270,24 @@ paths: - name: tool in: path description: The tool category to list tools and language pairs for - type: string required: true - enum: - - mt - - dictionary + schema: + type: string + enum: + - mt + - dictionary - name: from in: path description: The source language code - type: string required: true + schema: + type: string - name: to in: path description: The target language code - type: string required: true + schema: + type: string x-request-handler: - get_from_cx: request: @@ -257,49 +295,51 @@ paths: /list/languagepairs/: get: - tags: ['Transform'] + tags: + - Transform summary: Lists the language pairs supported by the back-end description: | Fetches the list of language pairs the back-end service can translate Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json responses: - '200': + 200: description: the list of source and target languages supported by the API - schema: - $ref: '#/definitions/cx_languagepairs' + content: + application/json: + schema: + $ref: '#/components/schemas/cx_languagepairs' x-monitor: false x-request-handler: - get_from_cx: request: uri: '{{options.cx_host}}/v1/list/languagepairs' -definitions: - cx_list_tools: - type: object - properties: - tools: - type: array - description: the list of tools available for the given language pair - items: - type: string - description: the tool available - cx_list_pairs_for_tool: - type: object - cx_languagepairs: - type: object - properties: - source: - type: array - description: the list of available source languages - items: - type: string - description: one source language - target: - type: array - description: the list of available destination languages - items: - type: string - description: one destination language +components: + schemas: + cx_list_tools: + type: object + properties: + tools: + type: array + description: the list of tools available for the given language pair + items: + type: string + description: the tool available + cx_list_pairs_for_tool: + type: object + cx_languagepairs: + type: object + properties: + source: + type: array + description: the list of available source languages + items: + type: string + description: one source language + target: + type: array + description: the list of available destination languages + items: + type: string + description: one destination language diff --git a/v1/transform-lang.yaml b/v1/transform-lang.yaml index e1ccce84f..ad4c21a64 100644 --- a/v1/transform-lang.yaml +++ b/v1/transform-lang.yaml @@ -1,5 +1,6 @@ +openapi: 3.0.1 info: - version: '1.0.0' + version: 1.0.0 title: Transform API description: Transform API termsOfService: https://github.com/wikimedia/restbase @@ -9,39 +10,46 @@ info: paths: /html/from/{from}: post: &html_from_from_post_spec - tags: ['Transforms'] + tags: + - Transforms summary: Machine-translate content description: | Fetches the machine translation for the posted content from the source to the language of this wiki. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - consumes: - - application/x-www-form-urlencoded - produces: - - application/json - - application/problem+json parameters: - name: from in: path description: The source language code - type: string required: true - - name: html - in: formData - description: The HTML content to translate - type: string - required: true - x-textarea: true + schema: + type: string + requestBody: + content: + application/x-www-form-urlencoded: + schema: + required: + - html + properties: + html: + type: string + description: The HTML content to translate + x-textarea: true + required: true responses: - '200': + 200: description: The translated content - schema: - $ref: '#/definitions/cx_mt' + content: + application/json: + schema: + $ref: '#/components/schemas/cx_mt' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false operationId: doMT @@ -53,59 +61,71 @@ paths: - name: from in: path description: The source language code - type: string required: true + schema: + type: string - name: provider in: path description: The machine translation provider id - type: string - required: true - enum: - - Apertium - - Yandex - - Youdao - - name: html - in: formData - description: The HTML content to translate - type: string required: true - x-textarea: true - + schema: + type: string + enum: + - Apertium + - Yandex + - Youdao + requestBody: + content: + multipart/form-data: + schema: + required: + - html + properties: + html: + type: string + description: The HTML content to translate + x-textarea: true + required: true + /word/from/{from}/{word}: get: &word_from_from_word_get_spec - tags: ['Transforms'] + tags: + - Transforms summary: Fetch the dictionary meaning of a word description: | Fetches the dictionary meaning of a word from a language and displays it in the target language. Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - produces: - - application/json - - application/problem+json parameters: - name: from in: path description: The source language code - type: string required: true + schema: + type: string - name: word in: path description: The word to lookup - type: string required: true + schema: + type: string responses: - '200': + 200: description: the dictionary translation for the given word - schema: - $ref: '#/definitions/cx_dict' + content: + application/json: + schema: + $ref: '#/components/schemas/cx_dict' default: description: Error - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-monitor: false operationId: doDict - + /word/from/{from}/{word}/{provider}: get: <<: *word_from_from_word_get_spec @@ -114,18 +134,21 @@ paths: - name: from in: path description: The source language code - type: string required: true + schema: + type: string - name: word in: path description: The word to lookup - type: string required: true + schema: + type: string - name: provider in: path description: The dictionary provider id - type: string required: true - enum: - - JsonDict - - Dictd + schema: + type: string + enum: + - JsonDict + - Dictd diff --git a/v1/transform.yaml b/v1/transform.yaml index a5cf5a2cd..b448ba2d7 100644 --- a/v1/transform.yaml +++ b/v1/transform.yaml @@ -1,6 +1,6 @@ -swagger: '2.0' +openapi: 3.0.1 info: - version: '1.0.0-beta' + version: 1.0.0-beta title: MediaWiki Content API description: Basic MediaWiki content api. termsofservice: https://github.com/wikimedia/restbase#restbase @@ -32,56 +32,66 @@ paths: - Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable) - Rate limit: 25 req/s - consumes: - - multipart/form-data - produces: - - text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0" - - application/problem+json parameters: - - name: html - in: formData - description: The HTML to transform - type: string - required: true - x-textarea: true - - name: scrub_wikitext - in: formData - description: Normalise the DOM to yield cleaner wikitext? - type: boolean - required: false - name: if-match in: header description: | The `ETag` header of the original render indicating it's revision and timeuuid. Required if both `title` and `revision` parameters are present. - type: string - required: false - responses: - '200': - description: MediaWiki Wikitext. schema: type: string - '403': + requestBody: + content: + multipart/form-data: + schema: + required: + - html + properties: + html: + type: string + description: The HTML to transform + x-textarea: true + scrub_wikitext: + type: boolean + description: Normalise the DOM to yield cleaner wikitext? + required: true + responses: + 200: + description: MediaWiki Wikitext. + content: + text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0": + schema: + type: string + 403: description: Access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page title or revision - schema: - $ref: '#/definitions/problem' - '409': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 409: description: Revision was restricted - schema: - $ref: '#/definitions/problem' - '410': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 410: description: Page was deleted - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -107,27 +117,32 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string - required: true - - name: html - in: formData - description: The HTML to transform - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true - x-textarea: true - - name: scrub_wikitext - in: formData - description: Normalise the DOM to yield cleaner wikitext? - type: boolean - required: false + schema: + type: string - name: if-match in: header description: | The `ETag` header of the original render indicating it's revision and timeuuid. Required if both `title` and `revision` parameters are present. - type: string - required: false + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + required: + - html + properties: + html: + type: string + description: The HTML to transform + x-textarea: true + scrub_wikitext: + type: boolean + description: Normalise the DOM to yield cleaner wikitext? + required: true x-request-handler: - get_from_backend: request: @@ -144,32 +159,38 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The page revision - type: integer required: true - - name: html - in: formData - description: The HTML to transform - type: string - required: true - x-textarea: true - - name: scrub_wikitext - in: formData - description: Normalise the DOM to yield cleaner wikitext? - type: boolean - required: false + schema: + type: integer - name: if-match in: header description: | The `ETag` header of the original render indicating it's revision and timeuuid. Required if both `title` and `revision` parameters are present. - type: string - required: false + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + required: + - html + properties: + html: + type: string + description: The HTML to transform + x-textarea: true + scrub_wikitext: + type: boolean + description: Normalise the DOM to yield cleaner wikitext? + required: true x-request-handler: - get_from_backend: request: @@ -191,54 +212,61 @@ paths: - Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable) - Rate limit: 25 req/s - consumes: - - multipart/form-data - produces: - - text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.7.0" - - application/problem+json - parameters: - - name: wikitext - in: formData - description: The Wikitext to transform to HTML - type: string - required: true - x-textarea: true - - name: body_only - in: formData - description: Return only `body.innerHTML` - type: boolean - required: false - - name: stash - in: formData - description: Whether to temporarily stash the result of the transformation - type: boolean - required: false + requestBody: + content: + multipart/form-data: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to transform to HTML + x-textarea: true + body_only: + type: boolean + description: Return only `body.innerHTML` + stash: + type: boolean + description: Whether to temporarily stash the result of the transformation + required: true responses: - '200': + 200: description: See wikipage https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec - schema: - type: string - '403': + content: + text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.7.0": + schema: + type: string + 403: description: access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page title or revision - schema: - $ref: '#/definitions/problem' - '409': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 409: description: Revision was restricted - schema: - $ref: '#/definitions/problem' - '410': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 410: description: Page was deleted - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -263,25 +291,28 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true - - name: wikitext - in: formData - description: The Wikitext to transform to HTML - type: string - required: true - x-textarea: true - - name: body_only - in: formData - description: Return only `body.innerHTML` - type: boolean - required: false - - name: stash - in: formData - description: Whether to temporarily stash the result of the transformation - type: boolean - required: false + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to transform to HTML + x-textarea: true + body_only: + type: boolean + description: Return only `body.innerHTML` + stash: + type: boolean + description: Whether to temporarily stash the result of the transformation + required: true x-request-handler: - get_from_backend: request: @@ -312,30 +343,34 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The page revision - type: integer - required: true - - name: wikitext - in: formData - description: The Wikitext to transform to HTML - type: string required: true - x-textarea: true - - name: body_only - in: formData - description: Return only `body.innerHTML` - type: boolean - required: false - - name: stash - in: formData - description: Whether to temporarily stash the result of the transformation - type: boolean - required: false + schema: + type: integer + requestBody: + content: + multipart/form-data: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to transform to HTML + x-textarea: true + body_only: + type: boolean + description: Return only `body.innerHTML` + stash: + type: boolean + description: Whether to temporarily stash the result of the transformation + required: true x-request-handler: - get_from_backend: request: @@ -355,41 +390,58 @@ paths: - Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental) - Rate limit: 25 req/s - consumes: - - multipart/form-data - - application/json - produces: - - application/json - - application/problem+json - parameters: - - name: wikitext - in: formData - description: The Wikitext to check - type: string - required: true - x-textarea: true + requestBody: + content: + multipart/form-data: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to check + x-textarea: true + application/json: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to check + x-textarea: true + required: true responses: - '200': + 200: description: Linter errors, if any, as a JSON blob - schema: - type: object - '404': + content: + application/json: + schema: + type: object + 404: description: Unknown page title - schema: - $ref: '#/definitions/problem' - '409': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 409: description: Latest revision was restricted - schema: - $ref: '#/definitions/problem' - '410': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 410: description: Page was deleted - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route @@ -412,15 +464,22 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true - - name: wikitext - in: formData - description: The Wikitext to check - type: string - required: true - x-textarea: true + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to check + x-textarea: true + required: true x-request-handler: - get_from_backend: request: @@ -434,20 +493,28 @@ paths: parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The page revision - type: integer - required: true - - name: wikitext - in: formData - description: The Wikitext to check - type: string required: true - x-textarea: true + schema: + type: integer + requestBody: + content: + multipart/form-data: + schema: + required: + - wikitext + properties: + wikitext: + type: string + description: The Wikitext to check + x-textarea: true + required: true x-request-handler: - get_from_backend: request: @@ -530,7 +597,6 @@ paths: post: tags: - Transforms - summary: Transform modified HTML sections to Wikitext. description: | This entry point provides efficient HTML section edit functionality. @@ -539,78 +605,90 @@ paths: - Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable) - Rate limit: 25 req/s - consumes: - - application/json - produces: - - text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0" - - application/problem+json parameters: - name: title in: path - description: "Page title. Use underscores instead of spaces. Example: `Main_Page`." - type: string + description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.' required: true + schema: + type: string - name: revision in: path description: The page revision - type: integer - required: true - - in: body - name: section - description: Section changes to transform required: true schema: - type: object - properties: - changes: - type: object - example: - mwAg: - - html: '

Prepended section

' - - id: mwAg - - html: '

Appended Section

' - scrub_wikitext: - type: boolean - description: Normalise the DOM to yield cleaner wikitext? - required: - - changes + type: integer - name: if-match in: header description: | The `ETag` header of the original render indicating it's revision and timeuuid. Required if both `title` and `revision` parameters are present. - type: string - required: false - responses: - '200': - description: Wikitext of the full page. schema: type: string - '400': + requestBody: + description: Section changes to transform + content: + application/json: + schema: + required: + - changes + type: object + properties: + changes: + type: object + properties: {} + example: + mwAg: + - html:

Prepended section

+ - id: mwAg + - html:

Appended Section

+ scrub_wikitext: + type: boolean + description: Normalise the DOM to yield cleaner wikitext? + required: true + responses: + 200: + description: Wikitext of the full page. + content: + text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0": + schema: + type: string + 400: description: Illegal JSON provided or section id does not exist - schema: - $ref: '#/definitions/problem' - '403': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 403: description: access to the specific revision is restricted - schema: - $ref: '#/definitions/problem' - '404': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 404: description: Unknown page title or revision - schema: - $ref: '#/definitions/problem' - '409': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 409: description: Revision was restricted - schema: - $ref: '#/definitions/problem' - '410': + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' + 410: description: Page was deleted - schema: - $ref: '#/definitions/problem' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' default: description: Error - schema: - $ref: '#/definitions/problem' - + content: + application/problem+json: + schema: + $ref: '#/components/schemas/problem' x-route-filters: - type: default name: ratelimit_route