From 47142245903b388ea13660f3bb93f0bf76e45415 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 27 Nov 2023 17:49:09 +0100 Subject: [PATCH 01/29] Added openapi spec --- openapi.yaml | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 openapi.yaml diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000000..4113c847ca --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,2 @@ +openapi: 3.1.0 + From 2d36d30524cca3bc70fadc1185aff2c75c0b3416 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Tue, 28 Nov 2023 20:13:15 +0100 Subject: [PATCH 02/29] Implemented mock-up OpenAPI spec --- openapi.yaml | 283 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 4113c847ca..22c8e2a881 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,2 +1,285 @@ openapi: 3.1.0 +info: + title: WebService API Reference + description: BMO is Mozilla's highly customized version of Bugzilla. + license: + name: MPL-2.0 + url: https://github.com/mozilla-bteam/bmo/blob/master/LICENSE + version: 1.0.0 +servers: + - url: https://bugzilla.mozilla.org/rest + description: Production issue tracker for Firefox and other Mozilla products. + - url: https://bugzilla-dev.allizom.org/rest + description: Test instance for Bugzilla. + +paths: + /bug/{id_or_alias}/comment: + get: + tags: [Comments] + summary: Get all comments for a bug + description: This allows you to get all comments for a particular bug using the bug ID or alias. + parameters: + - name: id_or_alias + in: path + description: A single integer bug ID or alias. + required: true + schema: + type: + - string + - integer + - name: new_since + in: query + description: If specified, the method will only return comments newer than this time. + schema: + type: string + format: date-time + responses: + 200: + description: A list of Comments + content: + application/json: + schema: + type: object + properties: + bugs: + description: | + This is an object, where the keys are the numeric IDs of the bugs, and the value is a object with a single key, comments, which is an array of comments. + type: object + additionalProperties: + type: object + properties: + comments: + type: array + items: + $ref: "#/components/schemas/Comment" + comments: + type: object + example: + bugs: + 35: + comments: + - time: "2000-07-25T13:50:04Z" + text: "test bug to fix problem in removing from cc list." + bug_id: 35 + count: 0 + attachment_id: null + is_private: false + tags: [] + creator: user@bugzilla.org + creation_time: "2000-07-25T13:50:04Z" + id: 75 + + comments: {} + default: + description: (Invalid Comment ID) You specified an id in the “comment_ids” argument that is invalid–either you specified something that wasn’t a number, or there is no comment with that id. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + properties: + code: + const: 111 + + /bug/comment/{comment_id}: + get: + tags: [Comments] + summary: Get a specific comment + description: This allows you to get a specific comment based on the comment ID + parameters: + - name: comment_id + in: path + description: A single integer comment ID. + required: true + schema: + type: integer + responses: + 200: + description: A single Comment + content: + application/json: + schema: + type: object + properties: + comments: + description: This is an object, where the keys are the numeric IDs of the bugs, and the value is a object with a single key, comments, which is an array of comments. + type: object + additionalProperties: + $ref: "#/components/schemas/Comment" + bugs: + type: object + example: + comments: + 75: + time: "2000-07-25T13:50:04Z" + text: "test bug to fix problem in removing from cc list." + bug_id: 35 + count: 0 + attachment_id: null + is_private: false + tags: [] + creator: user@bugzilla.org + creation_time: "2000-07-25T13:50:04Z" + id: 75 + bugs: {} + default: + description: (Comment Is Private) You specified the id of a private comment in the “comment_ids” argument, and you are not in the “insider group” that can see private comments. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + properties: + code: + const: 110 + +components: + schemas: + Comment: + type: object + properties: + id: + description: The globally unique ID for the comment. + type: integer + bug_id: + description: The ID of the bug that this comment is on. + type: integer + attachment_id: + description: If the comment was made on an attachment, this will be the ID of that attachment. Otherwise it will be null. + type: + - integer + - null + count: + description: The number of the comment local to the bug. The Description is 0, comments start with 1. + type: integer + text: + description: The body of the comment, including any special text (such as “this bug was marked as a duplicate of…”). + type: string + raw_text: + description: The body of the comment without any special additional text. + type: string + creator: + description: The login name of the comment’s author. + type: string + time: + description: The time (in Bugzilla’s timezone) that the comment was added. + type: string + format: date-time + creation_time: + description: | + This is exactly same as the ``time`` key. Use this + field instead of ``time`` for consistency with other + methods including :ref:`rest_single_bug` and + :ref:`rest_attachments`. + + For compatibility, ``time`` is still usable. However, + please note that ``time`` may be deprecated and removed + in a future release. + type: string + format: date-time + is_private: + description: '``true`` if this comment is private (only visible to a certain group called the "insidergroup"), ``false`` otherwise.' + type: boolean + is_markdown: + description: '``true`` if this comment is private (only visible to a certain group called the "insidergroup"), ``false``' + type: boolean + Error: + type: object + properties: + error: + description: When an error occurs over REST, an object is returned with the key error set to true. + const: true + message: + type: string + code: + type: integer + +tags: + - name: Attachments + description: The Bugzilla API for creating, changing, and getting the details of attachments. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/attachment.html + - name: Bugs + description: This part of the Bugzilla REST API allows you to file new bugs in Bugzilla and to get information about existing bugs. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/bug.html + - name: Bug User Last Visited + description: Update the last-visited time for the specified bug and current user. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/bug-user-last-visit.html + - name: Bugzilla Information + description: These methods are used to get general configuration information about this Bugzilla instance. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/bugzilla.html + - name: Classifications + description: This part of the Bugzilla API allows you to deal with the available classifications. You will be able to get information about them as well as manipulate them. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/classification.html + - name: Comments + description: This allows you to get data about comments, given a bug ID or comment ID. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html + - name: Components + description: This part of the Bugzilla API looks at individual components and also allows updating their information. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/component.html + - name: Bug Fields + description: The Bugzilla API for getting details about bug fields. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/field.html + - name: Flag Activity + description: This API provides information about activity relating to bug and attachment flags. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/flag-activity.html + - name: General + description: This is the standard REST API for external programs that want to interact with Bugzilla. It provides a REST interface to various Bugzilla functions. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/general.html + - name: Github + description: | + This API endpoint is for creating attachments in a bug that are redirect links to a + specific Github pull request. This allows a bug viewer to click on the Github link + and be automatically redirected to the pull request. + + **Github Setup Instructions** + + * From the repository main page, click on the Settings tab. + * Click on Webhooks from the left side menu. + * Click on the Add Webhook button near the top right. + * For the payload url, enter ``https://bugzilla.mozilla.org/rest/github/pull_request``. + * Choose ``application/json`` for the content type. + * You will need to enter the signature secret obtained from a BMO admin (DO NOT SHARE). + * Make sure Enable SSL is turned on. + * Select "Let me select individual events" and only enable changes for "Pull Requests". + * Make sure at the bottom that "Active" is checked on. + * Save the webhook. + + > **Note:** + Past pull requests will not automatically get a link created in the bug. New pull + requests should get the link automatically when the pull request is first created. + + > **Note:** + The API endpoint looks at the pull request title for the bug id so + make sure the title is formatted correctly to allow the bug id to be determined. + Examples are: ``Bug 1234:``, ``Bug - 1234``, ``bug 1234``, or ``Bug 1234 -``. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/github.html + - name: Groups + description: The API for creating, changing, and getting information about groups. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/group.html + - name: Products + description: This part of the Bugzilla API allows you to list the available products and get information about them. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/product.html + - name: Users + description: This part of the Bugzilla API allows you to create user accounts, get information about user accounts and to log in or out using an existing account. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/user.html + - name: Webhooks + description: These methods are used to access information about and update your configured webhooks. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/extensions/Webhooks/api/v1/webhooks.html#list + +externalDocs: + description: Sphinx WebService API Reference + url: https://bugzilla.readthedocs.io/en/latest/api/ From 9240831625253b49d7bff49b6dd6a8f0d907e223 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Tue, 28 Nov 2023 20:33:30 +0100 Subject: [PATCH 03/29] Added "Create a comment on a bug" --- openapi.yaml | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 22c8e2a881..2c810dcaf4 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -123,7 +123,7 @@ paths: id: 75 bugs: {} default: - description: (Comment Is Private) You specified the id of a private comment in the “comment_ids” argument, and you are not in the “insider group” that can see private comments. + description: (Comment Is Private) You specified the id of a private comment in the “comment_ids” argument, and you are not in the “insider group” that can see private comments. content: application/json: schema: @@ -132,6 +132,84 @@ paths: code: const: 110 + /bug/{id}/comment: + post: + tags: [Comments] + summary: Create a comment on a bug + description: This allows you to add a comment to a bug in Bugzilla. All comments created via the API will be considered Markdown (specifically GitHub Flavored Markdown). + parameters: + - name: id + in: path + description: The ID or alias of the bug to append a comment to. + required: true + schema: + type: + - string + - integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: List of integer bug IDs to add the comment to. + type: array + items: + type: integer + comment: + description: The comment to append to the bug. If this is empty or all whitespace, an error will be thrown. + type: string + is_private: + description: If set to true, the comment is private, otherwise it is assumed to be public. + type: boolean + is_markdown: + description: "If true, the comment will be rendered as markdown. (default: ``false``)" + type: boolean + work_time: + description: Adds this many hours to the "Hours Worked" on the bug. If you are not in the time tracking group, this value will be ignored. + type: number + required: + - comment + additionalProperties: false + example: + ids: + - 123 + - 456 + comment: "This is an additional comment" + is_private: false + is_markdown: true + work_time: 2.5 + + responses: + 200: + description: ID of the newly-created comment + content: + application/json: + schema: + type: object + properties: + id: + type: integer + example: + id: 789 + default: + description: | + Various error responses, including: + + * 54 (Hours Worked Too Large) + * 100 (Invalid Bug Alias) + * 101 (Invalid Bug ID) + * 109 (Bug Edit Denied) + * 113 (Can't Make Private Comments) + * 114 (Comment Too Long) + * 140 (Markdown Disabled) + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + components: schemas: Comment: From 6f2edce8d635f4adb5e7268369807326aff36f91 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Tue, 28 Nov 2023 20:45:04 +0100 Subject: [PATCH 04/29] Added "Update tags for a comment" --- openapi.yaml | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 2c810dcaf4..1048bfc7de 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -210,6 +210,72 @@ paths: schema: $ref: "#/components/schemas/Error" + /bug/comment/{comment_id}/tags: + put: + tags: [Comments] + summary: Update tags for a comment + description: Adds or removes tags from a comment. + parameters: + - name: comment_id + in: path + description: The ID of the comment to update. + required: true + schema: + type: integer + example: 75 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + add: + description: The tags to attach to the comment. + type: array + items: + type: string + remove: + description: The tags to detach from the comment. + type: array + items: + type: string + # QUESTION: should the parameter be in the body? + # https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html#update-comment-tags + required: + - comment_id + additionalProperties: false + example: + # comment_id: 75 + add: + - "spam" + - "bad" + + responses: + 200: + description: An array of strings containing the comment's updated tags. + content: + application/json: + schema: + type: array + items: + type: string + example: + - "bad" + - "spam" + default: + description: | + Various error responses, including: + + * 125 (Comment Tagging Disabled) + * 126 (Invalid Comment Tag) + * 127 (Comment Tag Too Short) + * 128 (Comment Tag Too Long) + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + components: schemas: Comment: From 19d3d1ebd71962870100b87ba4e4bdb88592fa91 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Tue, 28 Nov 2023 21:02:45 +0100 Subject: [PATCH 05/29] Removed custom property overrides since openapi-generator was complaining --- openapi.yaml | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 1048bfc7de..8ec870302c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -72,14 +72,20 @@ paths: comments: {} default: - description: (Invalid Comment ID) You specified an id in the “comment_ids” argument that is invalid–either you specified something that wasn’t a number, or there is no comment with that id. + description: | + Various error responses, including: + + * 100 (Invalid Bug Alias) + If you specified an alias and there is no bug with that alias. + * 101 (Invalid Bug ID) + The bug_id you specified doesn't exist in the database. + * 102 (Access Denied) + You do not have access to the bug_id you specified. + content: application/json: schema: $ref: "#/components/schemas/Error" - properties: - code: - const: 111 /bug/comment/{comment_id}: get: @@ -123,14 +129,17 @@ paths: id: 75 bugs: {} default: - description: (Comment Is Private) You specified the id of a private comment in the “comment_ids” argument, and you are not in the “insider group” that can see private comments. + description: | + Various error responses, including: + + * 110 (Comment Is Private) + You specified the id of a private comment in the “comment_ids” argument, and you are not in the “insider group” that can see private comments. + * 111 (Invalid Comment ID) + You specified an id in the “comment_ids” argument that is invalid–either you specified something that wasn’t a number, or there is no comment with that id. content: application/json: schema: $ref: "#/components/schemas/Error" - properties: - code: - const: 110 /bug/{id}/comment: post: From c46ecf1dbeefdf7d18b3a13a76fa79613837e887 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Tue, 28 Nov 2023 21:07:46 +0100 Subject: [PATCH 06/29] Added "Search for comment tags" --- openapi.yaml | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 8ec870302c..cfab6363f5 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -219,6 +219,45 @@ paths: schema: $ref: "#/components/schemas/Error" + /bug/comment/tags/{query}: + get: + tags: [Comments] + summary: Search for comment tags + description: Searches for tags which contain the provided substring. + parameters: + - name: query + in: path + description: Only tags containing this substring will be returned. + required: true + schema: + type: string + - name: limit + in: query + description: If provided, will return no more than "limit" tags. Defaults to "10". + schema: + type: integer + default: 10 + responses: + 200: + description: An array of matching tags + content: + application/json: + schema: + type: array + items: + type: string + example: + - "spam" + default: + description: | + Various error responses, including: + + * 125 (Comment Tagging Disabled) + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /bug/comment/{comment_id}/tags: put: tags: [Comments] From 8829dcdcfcf223e3f9c7719e291b90843af64b6c Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Tue, 28 Nov 2023 21:12:40 +0100 Subject: [PATCH 07/29] Added "Render comment as HTML" --- openapi.yaml | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index cfab6363f5..3fb1755656 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -324,6 +324,50 @@ paths: schema: $ref: "#/components/schemas/Error" + /bug/comment/render: + post: + tags: [Comments] + summary: Render comment as HTML + description: Returns the HTML rendering of the provided comment text. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + text: + description: Comment text to render. + type: string + id: + description: The ID of the bug to render the comment against. + type: integer + required: + - text + additionalProperties: false + example: + text: "This issue has been fixed in bug 1234." + id: 2345 + responses: + 200: + description: Text containing the HTML rendering + content: + application/json: + schema: + type: object + properties: + html: + type: string + example: + html: 'This issue has been fixed in bug 1234.' + default: + description: | + Various error responses, including those thrown by :ref:`rest_single_bug`. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + components: schemas: Comment: From 895ef679edbd61f200b6469bcd0c4c2f1176c949 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Wed, 29 Nov 2023 22:53:57 +0100 Subject: [PATCH 08/29] Added "Get Bug" --- openapi.yaml | 334 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 3fb1755656..54a30ebba1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -14,6 +14,129 @@ servers: description: Test instance for Bugzilla. paths: + # Bugs + /bug/{id_or_alias}: + get: + tags: [Bugs] + summary: Get information about a bug + description: Gets information about a particular bug using its ID or alias. + parameters: + - name: id_or_alias + in: path + description: An integer bug ID or a bug alias string. + required: true + schema: + type: + - string + - integer + responses: + 200: + description: A list of Bugs + content: + application/json: + schema: + type: object + properties: + faults: + type: array + bugs: + type: array + items: + $ref: "#/components/schemas/Bug" + example: + faults: [] + bugs: + - assigned_to_detail: + id: 2 + real_name: "Test User" + nick: "user" + name: "user@bugzilla.org" + email: "user@bugzilla.org" + flags: + - type_id: 11 + modification_date: "2014-09-28T21:03:47Z" + name: "blocker" + status: "?" + id: 2906 + setter: "user@bugzilla.org" + creation_date: "2014-09-28T21:03:47Z" + resolution: "INVALID" + id: 35 + type: "defect" + qa_contact: "" + triage_owner: "" + version: "1.0" + status: "RESOLVED" + creator: "user@bugzilla.org" + cf_drop_down: "---" + summary: "test bug" + last_change_time: "2014-09-23T19:12:17Z" + platform: "All" + url: "" + classification: "Unclassified" + cc_detail: + - id: 786 + real_name: "Foo Bar" + nick: "foo" + name: "foo@bar.com" + email: "foo@bar.com" + priority: "P1" + is_confirmed: true + creation_time: "2000-07-25T13:50:04Z" + assigned_to: "user@bugzilla.org" + alias: null + cf_large_text: "" + groups: [] + op_sys: "All" + cf_bug_id: null + depends_on: [] + is_cc_accessible: true + is_open: false + cf_qa_list_4: "---" + keywords: [] + cc: + - "foo@bar.com" + see_also: [] + deadline: null + is_creator_accessible: true + whiteboard: "" + dupe_of: null + duplicates: [] + target_milestone: "---" + cf_mulitple_select: [] + component: "SaltSprinkler" + severity: "critical" + cf_date: null + product: "FoodReplicator" + creator_detail: + id: 28 + real_name: "hello" + nick: "namachi" + name: "user@bugzilla.org" + email: "namachi@netscape.com" + cf_free_text: "" + blocks: [] + regressed_by: [] + regressions: [] + comment_count: 12 + + default: + description: | + Various error responses, including: + + * 100 (Invalid Bug Alias) + If you specified an alias and there is no bug with that alias. + * 101 (Invalid Bug ID) + The bug_id you specified doesn't exist in the database. + * 102 (Access Denied) + You do not have access to the bug_id you specified. + + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + + # Comments /bug/{id_or_alias}/comment: get: tags: [Comments] @@ -370,6 +493,217 @@ paths: components: schemas: + Bug: + type: object + properties: + actual_time: + description: The total number of hours that this bug has taken so far. + type: number + alias: + description: The unique alias of this bug. A null value will be returned if this bug has no alias. + type: string + assigned_to: + description: The login name of the user to whom the bug is assigned. + type: string + assigned_to_detail: + $ref: "#/components/schemas/User" + blocks: + description: The IDs of bugs that are "blocked" by this bug. + type: array + items: + type: integer + cc: + description: The login names of users on the CC list of this bug. + type: array + items: + type: string + cc_detail: + description: Array of objects containing detailed user information for each of the cc list members. + type: array + items: + $ref: "#/components/schemas/User" + classification: + description: The name of the current classification the bug is in. + type: string + component: + description: The name of the current component of this bug. + type: string + creation_time: + description: When the bug was created. + type: string + format: date-time + creator: + description: The login name of the person who filed this bug (the reporter). + type: string + creator_detail: + $ref: "#/components/schemas/User" + deadline: + description: The day that this bug is due to be completed, in the format YYYY-MM-DD. + type: string + depends_on: + description: The IDs of bugs that this bug "depends on". + type: array + items: + type: integer + dupe_of: + description: The bug ID of the bug that this bug is a duplicate of. If this bug isn't a duplicate of any bug, this will be null. + type: integer + duplicates: + description: The ids of bugs that are marked as duplicate of this bug. + type: array + items: + type: integer + estimated_time: + description: The number of hours that it was estimated that this bug would take. + type: number + flags: + description: An array of objects containing the information about flags currently set for the bug. + type: array + items: + $ref: "#/components/schemas/Flag" + groups: + description: The names of all the groups that this bug is in. + type: array + items: + type: string + id: + description: The unique numeric ID of this bug. + type: integer + is_cc_accessible: + description: If true, this bug can be accessed by members of the CC list, even if they are not in the groups the bug is restricted to. + type: boolean + is_confirmed: + description: true if the bug has been confirmed. Usually this means that the bug has at some point been moved out of the UNCONFIRMED status and into another open status. + type: boolean + is_creator_accessible: + description: If true, this bug can be accessed by the creator of the bug, even if they are not a member of the groups the bug is restricted to. + type: boolean + keywords: + description: Each keyword that is on this bug. + type: array + items: + type: string + last_change_time: + description: When the bug was last changed. + type: string + format: date-time + op_sys: + description: The name of the operating system that the bug was filed against. + type: string + platform: + description: The name of the platform (hardware) that the bug was filed against. + type: string + priority: + description: The priority of the bug. + type: string + product: + description: The name of the product this bug is in. + type: string + qa_contact: + description: The login name of the current QA Contact on the bug. + type: string + qa_contact_detail: + $ref: "#/components/schemas/User" + regressed_by: + description: The IDs of bugs that introduced this bug. + type: array + items: + type: integer + regressions: + description: The IDs of bugs that are introduced by this bug. + type: array + items: + type: integer + remaining_time: + description: The number of hours of work remaining until work on this bug is complete. + type: number + resolution: + description: The current resolution of the bug, or an empty string if the bug is open. + type: string + see_also: + description: The URLs in the See Also field on the bug. + type: array + items: + type: string + severity: + description: The current severity of the bug. + type: string + status: + description: The current status of the bug. + type: string + summary: + description: The summary of this bug. + type: string + target_milestone: + description: The milestone that this bug is supposed to be fixed by, or for closed bugs, the milestone that it was fixed for. + type: string + type: + description: The type of the bug. + type: string + update_token: + description: The token that you would have to pass to the process_bug.cgi page in order to update this bug. This changes every time the bug is updated. This field is not returned to logged-out users. + type: string + url: + description: A URL that demonstrates the problem described in the bug, or is somehow related to the bug report. + type: string + version: + description: The version the bug was reported against. + type: string + whiteboard: + description: The value of the "status whiteboard" field on the bug. + type: string + # Custom fields? + # Extra fields? + + Flag: + type: object + properties: + id: + description: The ID of the flag. + type: integer + name: + description: The name of the flag. + type: string + type_id: + description: The type ID of the flag. + type: integer + creation_date: + description: The timestamp when this flag was originally created. + type: string + format: date-time + modification_date: + description: The timestamp when the flag was last modified. + type: string + format: date-time + status: + description: The current status of the flag. + type: string + setter: + description: The login name of the user who created or last modified the flag. + type: string + requestee: + description: The login name of the user this flag has been requested to be granted or denied. Note, this field is only returned if a requestee is set. + type: string + + User: + type: object + properties: + id: + description: The user ID for this user. + type: integer + real_name: + description: The 'real' name for this user, if any. + type: string + nick: + description: The user's nickname. Currently, this is extracted from the real_name, name, or email field. + type: string + name: + description: The user's Bugzilla login. + type: string + email: + description: The user's email address. Currently, this is the same value as the name. + type: string + Comment: type: object properties: From 72b81a01bb3c7d0e958a546980114258e5707bda Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Wed, 29 Nov 2023 22:59:01 +0100 Subject: [PATCH 09/29] Added "Bug History" --- openapi.yaml | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 54a30ebba1..e55581342e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -136,6 +136,62 @@ paths: schema: $ref: "#/components/schemas/Error" + /bug/{id}/history: + get: + tags: [Bugs] + summary: Get the history of changes for a specific bug + description: | + Gets the history of changes for a particular bug in the database. You can specify a bug ID or alias and, optionally, a datetime timestamp to only show history since that date. + parameters: + - name: id + in: path + description: An integer bug ID or alias. + required: true + schema: + type: + - string + - integer + - name: new_since + in: query + description: A datetime timestamp to only show history since. + schema: + type: string + format: date-time + responses: + 200: + description: A list of bugs with their history + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: "#/components/schemas/BugWithHistory" + example: + bugs: + - id: 35 + alias: null + history: + - when: "2014-09-23T19:12:17Z" + who: "user@bugzilla.org" + changes: + - field_name: "priority" + added: "P1" + removed: "P2" + - field_name: "severity" + added: "critical" + removed: "blocker" + - when: "2014-09-28T21:03:47Z" + who: "user@bugzilla.org" + changes: + - field_name: "flagtypes.name" + added: "blocker?" + removed: "" + default: + $ref: "#/components/schemas/Error" + # Comments /bug/{id_or_alias}/comment: get: @@ -704,6 +760,54 @@ components: description: The user's email address. Currently, this is the same value as the name. type: string + BugWithHistory: + type: object + properties: + id: + description: The numeric ID of the bug. + type: integer + alias: + description: The unique alias of this bug. A null value will be returned if this bug has no alias. + type: string + history: + description: An array of History objects. + type: array + items: + $ref: "#/components/schemas/History" + + History: + type: object + properties: + when: + description: The date the bug activity/change happened. + type: string + format: date-time + who: + description: The login name of the user who performed the bug change. + type: string + changes: + description: An array of Change objects. + type: array + items: + $ref: "#/components/schemas/Change" + + Change: + type: object + properties: + field_name: + description: The name of the bug field that has changed. + type: string + removed: + description: The previous value of the bug field which has been deleted by the change. + type: string + added: + description: The new value of the bug field which has been added by the change. + type: string + attachment_id: + description: The ID of the attachment that was changed. This only appears if the change was to an attachment, otherwise `attachment_id` will not be present in this object. + type: integer + nullable: true + Comment: type: object properties: From eb7edf396b1c5cd91bbe367a650d4df331cb4a47 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Wed, 29 Nov 2023 23:06:50 +0100 Subject: [PATCH 10/29] Added "Search Bugs" --- openapi.yaml | 216 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 215 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index e55581342e..4a3db3e31a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -190,7 +190,221 @@ paths: added: "blocker?" removed: "" default: - $ref: "#/components/schemas/Error" + description: | + Same as Get Bug. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + + /bug: + get: + tags: [Bugs] + summary: Search for bugs based on particular criteria + description: | + Allows you to search for bugs based on specific criteria. Bugs are returned if they match the criteria specified. Criteria are joined in a logical AND, meaning bugs returned must match all of the specified criteria. + parameters: + - name: alias + in: query + description: The unique alias of this bug. A null value will be returned if this bug has no alias. + schema: + type: string + - name: assigned_to + in: query + description: The login name of a user that a bug is assigned to. + schema: + type: string + - name: component + in: query + description: The name of the Component that the bug is in. + schema: + type: string + - name: count_only + in: query + description: If set to true, an object with a single key called "bug_count" will be returned, which is the number of bugs that matched the search. + schema: + type: boolean + - name: creation_time + in: query + description: Searches for bugs that were created at this time or later. May not be an array. + schema: + type: string + format: date-time + - name: creator + in: query + description: The login name of the user who created the bug. + schema: + type: string + - name: description + in: query + description: The description (initial comment) of the bug. + schema: + type: string + - name: filed_via + in: query + description: Searches for bugs that were created with this method. + schema: + type: string + - name: id + in: query + description: The numeric ID of the bug. + schema: + type: integer + - name: last_change_time + in: query + description: Searches for bugs that were modified at this time or later. May not be an array. + schema: + type: string + format: date-time + - name: limit + in: query + description: Limit the number of results returned. + schema: + type: integer + - name: longdescs.count + in: query + description: The number of comments a bug has. + schema: + type: integer + - name: offset + in: query + description: Used in conjunction with the limit argument, offset defines the starting position for the search. + schema: + type: integer + - name: op_sys + in: query + description: The "Operating System" field of a bug. + schema: + type: string + - name: platform + in: query + description: The Platform (sometimes called "Hardware") field of a bug. + schema: + type: string + - name: priority + in: query + description: The Priority field on a bug. + schema: + type: string + - name: product + in: query + description: The name of the Product that the bug is in. + schema: + type: string + - name: quicksearch + in: query + description: Search for bugs using quicksearch syntax. + schema: + type: string + - name: resolution + in: query + description: The current resolution--only set if a bug is closed. + schema: + type: string + - name: severity + in: query + description: The Severity field on a bug. + schema: + type: string + - name: status + in: query + description: The current status of a bug (not including its resolution, if it has one, which is a separate field above). + schema: + type: string + - name: summary + in: query + description: Searches for substrings in the single-line Summary field on bugs. + schema: + type: string + - name: tags + in: query + description: Searches for a bug with the specified tag. + schema: + type: string + - name: target_milestone + in: query + description: The Target Milestone field of a bug. + schema: + type: string + - name: qa_contact + in: query + description: The login name of the bug's QA Contact. + schema: + type: string + - name: triage_owner + in: query + description: The login name of the Triage Owner of a bug's component. + schema: + type: string + - name: type + in: query + description: The Type field on a bug. + schema: + type: string + - name: url + in: query + description: The "URL" field of a bug. + schema: + type: string + - name: version + in: query + description: The Version field of a bug. + schema: + type: string + - name: whiteboard + in: query + description: Search the "Status Whiteboard" field on bugs for a substring. + schema: + type: string + responses: + 200: + description: A list of bugs matching the search criteria + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: "#/components/schemas/Bug" + example: + bugs: + - id: 35 + alias: null + assigned_to: "user@bugzilla.org" + component: "Widgets" + creation_time: "2014-09-23T19:12:17Z" + creator: "user@bugzilla.org" + description: "Bug description goes here." + filed_via: "REST API" + last_change_time: "2014-09-28T21:03:47Z" + op_sys: "All" + platform: "All" + priority: "P1" + product: "MyProduct" + resolution: null + severity: "critical" + status: "NEW" + summary: "Bug summary goes here." + tags: null + target_milestone: "---" + qa_contact: null + triage_owner: null + type: "defect" + url: null + version: null + whiteboard: null + longdescs_count: 2 + default: + description: | + If you specify an invalid value for a particular field, you just won’t get any results for that value. + + * 1000 (Parameters Required) You may not search without any search terms. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" # Comments /bug/{id_or_alias}/comment: From 5b59eb15305abe0a304ee6cd9941527ba6e2849c Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Wed, 29 Nov 2023 23:28:58 +0100 Subject: [PATCH 11/29] Added "Create Bug" --- openapi.yaml | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 4a3db3e31a..88d8bd1927 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -406,6 +406,85 @@ paths: schema: $ref: "#/components/schemas/Error" + post: + tags: [Bugs] + summary: Create a new bug + description: | + This endpoint allows you to create a new bug in Bugzilla. If you specify any + invalid fields, an error will be thrown stating which field is invalid. + If you specify any fields you are not allowed to set, they will just be + set to their defaults or ignored. + + You cannot currently set all the items here that you can set on enter_bug.cgi. + + The WebService interface may allow you to set things other than those listed + here, but realize that anything undocumented here may likely change in the + future. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/NewBug" + example: + product: TestProduct + component: TestComponent + version: unspecified + summary: "This is a test bug - please disregard" + alias: SomeAlias + op_sys: All + priority: P1 + platform: All + type: defect + responses: + "200": + description: A successful bug creation response + content: + application/json: + schema: + type: object + properties: + id: + type: integer + description: This is the ID of the newly-filed bug. + example: + id: 12345 + + default: + description: | + Various error responses, including: + + * 51 (Invalid Object) + You specified a field value that is invalid. The error message will have more details. + * 103 (Invalid Alias) + The alias you specified is invalid for some reason. See the error message for more details. + * 104 (Invalid Field) + One of the drop-down fields has an invalid value, or a value entered in a text field is too long. The error message will have more detail. + * 105 (Invalid Component) + You didn't specify a component. + * 106 (Invalid Product) + Either you didn't specify a product, this product doesn't exist, or you don't have permission to enter bugs in this product. + * 107 (Invalid Summary) + You didn't specify a summary for the bug. + * 116 (Dependency Loop) + You specified values in the "blocks" and "depends_on" fields, or the "regressions" and "regressed_by" fields, that would cause a circular dependency between bugs. + * 120 (Group Restriction Denied) + You tried to restrict the bug to a group which does not exist, or which you cannot use with this product. + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 135 (Bug Type Required) + You didn't specify a type for the bug. + * 504 (Invalid User) + Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details. + deprecated: false + # Comments /bug/{id_or_alias}/comment: get: @@ -1022,6 +1101,120 @@ components: type: integer nullable: true + NewBug: + type: object + properties: + product: + type: string + description: The name of the product the bug is being filed against. + component: + type: string + description: The name of a component in the product above. + summary: + type: string + description: A brief description of the bug being filed. + version: + type: string + description: A version of the product above; the version the bug was found in. + description: + type: string + description: (defaulted) The description (initial comment) of the bug. Some Bugzilla installations require this to not be blank. + filed_via: + type: string + description: (defaulted) How the bug is being filed. It will be ``api`` by default when filing through the API. + op_sys: + type: string + description: (defaulted) The operating system the bug was discovered on. + platform: + type: string + description: (defaulted) What type of hardware the bug was experienced on. + priority: + type: string + description: (defaulted) What order the bug will be fixed in by the developer, compared to the developer's other bugs. + severity: + type: string + description: (defaulted) How severe the bug is. + type: + type: string + description: The basic category of the bug. Some Bugzilla installations require this to be specified. + alias: + type: string + description: The alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla. + assigned_to: + type: string + description: A user to assign this bug to, if you don't want it to be assigned to the component owner. + cc: + type: array + items: + type: string + description: An array of usernames to CC on this bug. + comment_is_private: + type: boolean + description: If set to true, the description is private, otherwise it is assumed to be public. + groups: + type: array + items: + type: string + description: An array of group names to put this bug into. You can see valid group names on the Permissions tab of the Preferences screen, or, if you are an administrator, in the Groups control panel. If you don't specify this argument, then the bug will be added into all the groups that are set as being "Default" for this product. (If you want to avoid that, you should specify ``groups`` as an empty array.) + qa_contact: + type: string + description: If this installation has QA Contacts enabled, you can set the QA Contact here if you don't want to use the component's default QA Contact. + status: + type: string + description: The status that this bug should start out as. Note that only certain statuses can be set on bug creation. + resolution: + type: string + description: If you are filing a closed bug, then you will have to specify a resolution. You cannot currently specify a resolution of ``DUPLICATE`` for new bugs, though. That must be done with :ref:`rest_update_bug`. + target_milestone: + type: string + description: A valid target milestone for this product. + flags: + type: array + items: + $ref: "#/components/schemas/NewFlag" + keywords: + type: array + items: + type: string + description: One or more valid keywords to add to this bug. + dependson: + type: array + items: + type: integer + description: One or more valid bug ids that this bug depends on. + blocked: + type: array + items: + type: integer + description: One or more valid bug ids that this bug blocks. + regressed_by: + type: array + items: + type: integer + description: One or more valid bug ids that introduced this bug. + required: + - product + - component + - summary + - version + - type + + NewFlag: + type: object + properties: + name: + type: string + description: The name of the flag type. + type_id: + type: integer + description: The internal flag type ID. + status: + type: string + description: The flags new status (i.e. "?", "+", "-" or "X" to clear flag). + requestee: + type: string + description: The login of the requestee if the flag type is requestable to a specific user. + Comment: type: object properties: From 257905d8372b817d6ab884b93df251279e0742d6 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 30 Nov 2023 12:19:23 +0100 Subject: [PATCH 12/29] Added "Graph" --- openapi.yaml | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 88d8bd1927..35d27f4bfa 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -485,6 +485,133 @@ paths: Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details. deprecated: false + /bug/{bug_id}/graph: + get: + tags: [Bugs] + summary: Return a graph of bug relationships + description: Return a graph of bug relationships such as dependencies, regressions, and duplicates. By default, resolved bugs are not returned but can be if needed. The bug ID provided will be the root node of the graph. + parameters: + - name: bug_id + in: path + description: The bug ID that will be the root node of the graph. + required: true + schema: + type: integer + - name: ids_only + in: query + description: Do not return simple bug data with each bug ID in the tree. + schema: + type: boolean + default: false + - name: depth + in: query + description: Limit the depth of the graph. + schema: + type: integer + default: 3 + maximum: 9 + - name: show_resolved + in: query + description: Enable if you want to also see RESOLVED bugs in the graph. + schema: + type: boolean + default: false + - name: relationship + in: query + description: One of "dependencies", "duplicates", or "regressions". + schema: + type: string + default: "dependencies" + enum: ["dependencies", "duplicates", "regressions"] + responses: + 200: + description: | + A graph of bug relationships + + The default return object will be an object with two trees based on the type of relationship selected. For dependencies, it will be blocked and dependson. For regressions, it will be be regresses and regressed_by. And for duplicates, it will be dupe_of and dupe. + content: + application/json: + schema: + oneOf: + - type: object + properties: + blocked: + $ref: "#/components/schemas/BugNode" + dependson: + $ref: "#/components/schemas/BugNode" + - type: object + properties: + regresses: + $ref: "#/components/schemas/BugNode" + regressed_by: + $ref: "#/components/schemas/BugNode" + - type: object + properties: + dupe_of: + $ref: "#/components/schemas/BugNode" + dupe: + $ref: "#/components/schemas/BugNode" + + example: + blocked: + 2: + 3: + bug: + alias: null + id: 3 + is_confirmed: 1 + op_sys: Unspecified + platform: Unspecified + priority: -- + resolution: "" + severity: normal + status: NEW + summary: Another new test bug + target_milestone: --- + type: defect + url: "" + version: unspecified + whiteboard: "" + bug: + alias: null + id: 2 + is_confirmed: 1 + op_sys: Unspecified + platform: Unspecified + priority: -- + resolution: "" + severity: normal + status: NEW + summary: this is a new test bug + target_milestone: --- + type: defect + url: "" + version: unspecified + whiteboard: "" + bug: + alias: null + id: 1 + is_confirmed: 1 + op_sys: Unspecified + platform: Unspecified + priority: -- + resolution: "" + severity: normal + status: NEW + summary: This is a new test bug + target_milestone: --- + type: defect + url: "" + version: unspecified + whiteboard: "" + dependson: {} + default: + description: Various error responses + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # Comments /bug/{id_or_alias}/comment: get: @@ -1215,6 +1342,14 @@ components: type: string description: The login of the requestee if the flag type is requestable to a specific user. + BugNode: + type: object + properties: + bug: + $ref: "#/components/schemas/Bug" + additionalProperties: + $ref: "#/components/schemas/BugNode" + Comment: type: object properties: @@ -1263,6 +1398,7 @@ components: is_markdown: description: '``true`` if this comment is private (only visible to a certain group called the "insidergroup"), ``false``' type: boolean + Error: type: object properties: From 6f2e337801f7bdd95cc048f195d958e2512835eb Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 30 Nov 2023 12:29:55 +0100 Subject: [PATCH 13/29] Added "Possible Duplicates" --- openapi.yaml | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 35d27f4bfa..b62204e702 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -612,6 +612,71 @@ paths: schema: $ref: "#/components/schemas/Error" + /bug/possible_duplicates: + get: + tags: [Bugs] + summary: Gets a list of possible duplicate bugs + description: | + Gets a list of possible duplicate bugs based on a given bug ID or bug summary. + parameters: + - name: id + in: query + description: The ID of a bug to find duplicates of. + schema: + type: integer + - name: summary + in: query + description: A summary to search for duplicates of, only used if no bug ID is given. + schema: + type: string + - name: product + in: query + description: A product group to limit the search in. + schema: + type: string + - name: limit + in: query + description: | + Limit the number of results returned. If the value is unset, zero, or greater than + the maximum value set by the administrator (default: 10,000), the maximum value + will be used instead. + schema: + type: integer + responses: + 200: + description: A list of possible duplicate bugs + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: "#/components/schemas/BugWithHistory" + example: + bugs: + - id: 35 + alias: null + history: + - when: "2014-09-23T19:12:17Z" + who: user@bugzilla.org + changes: + - field_name: priority + added: "P1" + removed: "P2" + - field_name: severity + added: "critical" + removed: "blocker" + - when: "2014-09-28T21:03:47Z" + who: user@bugzilla.org + changes: + - field_name: flagtypes.name + added: "blocker?" + removed: "" + default: + description: Various error responses + # Comments /bug/{id_or_alias}/comment: get: From 38ba199d6517af887c709768deecc4f94cb81e99 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 30 Nov 2023 12:53:31 +0100 Subject: [PATCH 14/29] Added "Update Bug" --- openapi.yaml | 409 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index b62204e702..71745e1d10 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -135,6 +135,90 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" + put: + tags: [Bugs] + summary: Update a Bug + description: | + Allows you to update the fields of a bug. Automatically sends emails out about the changes. + parameters: + - name: id_or_alias + in: path + description: An integer bug ID or alias. + schema: + type: string + + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/BugUpdate" + example: + ids: + - 35 + status: IN_PROGRESS + keywords: + add: + - funny + - stupid + + responses: + 200: + description: A list of bugs that were updated + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: "#/components/schemas/UpdatedBug" + example: + bugs: + - alias: + changes: + keywords: + added: funny, stupid + removed: "" + status: + added: IN_PROGRESS + removed: CONFIRMED + id: 35 + last_change_time: "2014-09-29T14:25:35Z" + + default: + description: | + Various error responses, including: + + * 100 (Invalid Bug ID) + The bug_id you specified doesn't exist in the database. + * 102 (Access Denied) + You do not have access to the bug_id you specified. + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required + permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 132 (Flag not Unique) + The flag specified has been set multiple times. You must specify the id + value to update the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify + the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag of the "comment" to true but Markdown feature is + not enabled. + * 601 (Invalid MIME Type) + You specified a "content_type" argument that was blank, not a valid + MIME type, or not a MIME type that Bugzilla accepts for attachments. + * 603 (File Name Not Specified) + You did not specify a valid for the "file_name" argument. + * 604 (Summary Required) + You did not specify a value for the "summary" argument. /bug/{id}/history: get: @@ -1407,6 +1491,331 @@ components: type: string description: The login of the requestee if the flag type is requestable to a specific user. + BugUpdate: + type: object + required: + - ids + properties: + ids: + type: array + items: + type: + - integer + - string + description: The IDs or aliases of the bugs that you want to modify. + alias: + type: string + description: The alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla. + assigned_to: + type: string + description: The full login name of the user this bug is assigned to. + blocks: + type: object + description: Bugs that this bug blocks. + $ref: "#/components/schemas/BugRelationship" + depends_on: + type: object + description: Bugs that this bug depends on. + $ref: "#/components/schemas/BugRelationship" + regressions: + type: object + description: Bugs that this bug regresses. + $ref: "#/components/schemas/BugRelationship" + regressed_by: + type: object + description: Bugs that regress this bug. + $ref: "#/components/schemas/BugRelationship" + cc: + type: object + properties: + add: + type: array + items: + type: string + description: User names to add to the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name. + remove: + type: array + items: + type: string + description: User names to remove from the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name. + description: The users on the cc list. + is_cc_accessible: + type: boolean + description: Whether or not users in the CC list are allowed to access the bug. + comment: + type: object + properties: + body: + type: string + description: The actual text of the comment. + comment: + type: string + description: An alias for the comment body. (For compatibility with the parameters to rest_add_comment) + is_private: + type: boolean + description: Whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown. + description: A comment on the change. + comment_is_private: + type: object + description: | + This is how you update the privacy of comments that are already on a bug. + + This is a object, where the keys are the ID of comments. + + The comment IDs must be valid for the bug being updated. Thus, it is not practical to use this while updating multiple bugs at once, as a single comment ID will never be valid on multiple bugs. + additionalProperties: + type: boolean + description: Specifies whether that comment should become private (`true`) or public (`false`). + component: + type: string + description: The Component the bug is in. + deadline: + type: string + format: date + description: The Deadline field is a date specifying when the bug must be completed by. + dupe_of: + type: integer + description: | + The bug that this bug is a duplicate of. + + If you want to mark a bug as a duplicate, the safest thing to do is to set this value and not set the status or resolution fields. They will automatically be set by Bugzilla to the appropriate values for duplicate bugs. + estimated_time: + type: number + description: The total estimate of time required to fix the bug, in hours. + flags: + type: array + items: + $ref: "#/components/schemas/FlagChange" + description: | + An array of Flag change objects. + + Of any item, at least the status and one of type_id, id, or name must be specified. If a type_id or name matches a single currently set flag, the flag will be updated unless new is specified. + groups: + type: object + properties: + add: + type: array + items: + type: string + description: | + The names of groups to add. Passing in an invalid group name or a group that you cannot add to this bug will cause an error to be thrown. + remove: + type: array + items: + type: string + description: The names of groups to remove. Passing in an invalid group name or a group that you cannot remove from this bug will cause an error to be thrown. + description: The groups a bug is in. + keywords: + type: object + properties: + add: + type: array + items: + type: string + description: The names of keywords to add to the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. + remove: + type: array + items: + type: string + description: The names of keywords to remove from the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. + set: + type: array + items: + type: string + description: An exact set of keywords to set the field to, on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. Specifying `set` overrides `add` and `remove`. + description: Keywords on the bug. + op_sys: + type: string + description: The Operating System ("OS") field on the bug. + platform: + type: string + description: The Platform or "Hardware" field on the bug. + priority: + type: string + description: The Priority field on the bug. + product: + type: string + description: | + The name of the product that the bug is in. If + you change this, you will probably also want to + change ``target_milestone``, ``version``, and + ``component``, since those have different legal + values in every product. + + If you cannot change the ``target_milestone`` + field, it will be reset to the default for the + product, when you move a bug to a new product. + + You may also wish to add or remove groups, as + which groups are + valid on a bug depends on the product. Groups + that are not valid in the new product will be + automatically removed, and groups which are + mandatory in the new product will be + automatically added, but no other automatic group + changes will be done. + + > **Note:** + Users can only move a bug into a product if + they would normally have permission to file + new bugs in that product. + qa_contact: + type: string + description: The full login name of the bug's QA Contact. + is_creator_accessible: + type: boolean + description: Whether or not the bug's reporter is allowed to access the bug. + remaining_time: + type: number + description: | + How much work time is remaining to fix the bug, + in hours. If you set ``work_time`` but don't + explicitly set ``remaining_time``, then the + ``work_time`` will be deducted from the bug's + ``remaining_time``. + reset_assigned_to: + type: boolean + description: + If true, the `assigned_to` field will be reset to the default for the component that the bug is in. (If you have set the component at the + same time as using this, then the component used + will be the new component, not the old one.) + reset_qa_contact: + type: boolean + description: If true, the `qa_contact` field will be reset to the default for the component that the bug is in. + resolution: + type: string + description: The current resolution. May only be set if you + are closing a bug or if you are modifying an + already-closed bug. Attempting to set the + resolution to *any* value (even an empty or null + string) on an open bug will cause an error to be + thrown. + + > **Note:** + If you change the ``status`` field to an open + status, the resolution field will automatically + be cleared, so you don't have to clear it + manually. + see_also: + type: object + properties: + add: + type: array + items: + type: string + description: URLs to add to the field. Each + URL must be a valid URL to a bug-tracker, or + an error will be thrown. + remove: + type: array + items: + type: string + description: URLs to remove from the + field. Invalid URLs will be ignored. + description: The See Also field on a bug, specifying URLs to bugs in other bug trackers. + severity: + type: string + description: The Severity field of a bug. + status: + type: string + description: The status you want to change the bug to. Note that if a bug is changing from open to closed, you should also specify a `resolution`. + summary: + type: string + description: The Summary field of the bug. + target_milestone: + type: string + description: The bug's Target Milestone. + type: + type: string + description: The Type field on the bug. + url: + type: string + description: The "URL" field of a bug. + version: + type: string + description: The bug's Version field. + whiteboard: + type: string + description: The Status Whiteboard field of a bug. + work_time: + type: number + description: The number of hours worked on this bug as part + of this change. + If you set ``work_time`` but don't explicitly + set ``remaining_time``, then the ``work_time`` + will be deducted from the bug's ``remaining_time``. + + BugRelationship: + type: object + properties: + add: + type: array + items: + type: integer + description: Bug IDs to add to this field. + remove: + type: array + items: + type: integer + description: Bug IDs to remove from this field. If the bug IDs are not already in the field, they will be ignored. + set: + type: array + items: + type: integer + description: An exact set of bug IDs to set this field to, overriding the current value. If you specify `set`, then `add` and `remove` will be ignored. + + FlagChange: + type: object + properties: + name: + type: string + description: The name of the flag that will be created or updated. + type_id: + type: integer + description: The internal flag type ID that will be created or updated. + status: + type: string + description: The flags new status (i.e. "?", "+", "-" or "X" to clear a flag). + requestee: + type: string + description: The login of the requestee if the flag type is requestable to a specific user. + id: + type: integer + description: Use ID to specify the flag to be updated. + new: + type: boolean + description: Set to true if you specifically want a new flag to be created. + required: + - status + + UpdatedBug: + type: object + properties: + id: + type: integer + description: The ID of the bug that was updated. + alias: + type: string + description: The alias of the bug that was updated, if this bug has any alias. + last_change_time: + type: string + format: date-time + description: The exact time that this update was done at, for this bug. + changes: + type: object + additionalProperties: + $ref: "#/components/schemas/FieldChange" + + FieldChange: + type: object + properties: + added: + type: string + description: The values that were added to this field, possibly a comma-and-space-separated list if multiple values were added. + removed: + type: string + description: The values that were removed from this field, possibly a comma-and-space-separated list if multiple values were removed. + BugNode: type: object properties: From 5f4e994e608ed4f0fd030b33be6cb9e4c39d7372 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 30 Nov 2023 20:03:02 +0100 Subject: [PATCH 15/29] Let openapi-format reorder and format the file --- openapi.yaml | 620 +++++++++++++++++++++++---------------------------- 1 file changed, 284 insertions(+), 336 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 71745e1d10..f4f36e588b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4,20 +4,16 @@ info: description: BMO is Mozilla's highly customized version of Bugzilla. license: name: MPL-2.0 - url: https://github.com/mozilla-bteam/bmo/blob/master/LICENSE + url: "https://github.com/mozilla-bteam/bmo/blob/master/LICENSE" version: 1.0.0 - servers: - - url: https://bugzilla.mozilla.org/rest + - url: "https://bugzilla.mozilla.org/rest" description: Production issue tracker for Firefox and other Mozilla products. - - url: https://bugzilla-dev.allizom.org/rest + - url: "https://bugzilla-dev.allizom.org/rest" description: Test instance for Bugzilla. - paths: - # Bugs - /bug/{id_or_alias}: + "/bug/{id_or_alias}": get: - tags: [Bugs] summary: Get information about a bug description: Gets information about a particular bug using its ID or alias. parameters: @@ -30,7 +26,7 @@ paths: - string - integer responses: - 200: + "200": description: A list of Bugs content: application/json: @@ -48,46 +44,46 @@ paths: bugs: - assigned_to_detail: id: 2 - real_name: "Test User" - nick: "user" - name: "user@bugzilla.org" - email: "user@bugzilla.org" + real_name: Test User + nick: user + name: user@bugzilla.org + email: user@bugzilla.org flags: - type_id: 11 modification_date: "2014-09-28T21:03:47Z" - name: "blocker" + name: blocker status: "?" id: 2906 - setter: "user@bugzilla.org" + setter: user@bugzilla.org creation_date: "2014-09-28T21:03:47Z" - resolution: "INVALID" + resolution: INVALID id: 35 - type: "defect" + type: defect qa_contact: "" triage_owner: "" version: "1.0" - status: "RESOLVED" - creator: "user@bugzilla.org" + status: RESOLVED + creator: user@bugzilla.org cf_drop_down: "---" - summary: "test bug" + summary: test bug last_change_time: "2014-09-23T19:12:17Z" - platform: "All" + platform: All url: "" - classification: "Unclassified" + classification: Unclassified cc_detail: - id: 786 - real_name: "Foo Bar" - nick: "foo" - name: "foo@bar.com" - email: "foo@bar.com" - priority: "P1" + real_name: Foo Bar + nick: foo + name: foo@bar.com + email: foo@bar.com + priority: P1 is_confirmed: true creation_time: "2000-07-25T13:50:04Z" - assigned_to: "user@bugzilla.org" + assigned_to: user@bugzilla.org alias: null cf_large_text: "" groups: [] - op_sys: "All" + op_sys: All cf_bug_id: null depends_on: [] is_cc_accessible: true @@ -95,7 +91,7 @@ paths: cf_qa_list_4: "---" keywords: [] cc: - - "foo@bar.com" + - foo@bar.com see_also: [] deadline: null is_creator_accessible: true @@ -104,22 +100,21 @@ paths: duplicates: [] target_milestone: "---" cf_mulitple_select: [] - component: "SaltSprinkler" - severity: "critical" + component: SaltSprinkler + severity: critical cf_date: null - product: "FoodReplicator" + product: FoodReplicator creator_detail: id: 28 - real_name: "hello" - nick: "namachi" - name: "user@bugzilla.org" - email: "namachi@netscape.com" + real_name: hello + nick: namachi + name: user@bugzilla.org + email: namachi@netscape.com cf_free_text: "" blocks: [] regressed_by: [] regressions: [] comment_count: 12 - default: description: | Various error responses, including: @@ -130,13 +125,13 @@ paths: The bug_id you specified doesn't exist in the database. * 102 (Access Denied) You do not have access to the bug_id you specified. - content: application/json: schema: $ref: "#/components/schemas/Error" + tags: + - Bugs put: - tags: [Bugs] summary: Update a Bug description: | Allows you to update the fields of a bug. Automatically sends emails out about the changes. @@ -146,7 +141,6 @@ paths: description: An integer bug ID or alias. schema: type: string - requestBody: content: application/json: @@ -160,9 +154,8 @@ paths: add: - funny - stupid - responses: - 200: + "200": description: A list of bugs that were updated content: application/json: @@ -175,17 +168,16 @@ paths: $ref: "#/components/schemas/UpdatedBug" example: bugs: - - alias: + - alias: null changes: keywords: - added: funny, stupid + added: "funny, stupid" removed: "" status: added: IN_PROGRESS removed: CONFIRMED id: 35 last_change_time: "2014-09-29T14:25:35Z" - default: description: | Various error responses, including: @@ -219,10 +211,10 @@ paths: You did not specify a valid for the "file_name" argument. * 604 (Summary Required) You did not specify a value for the "summary" argument. - - /bug/{id}/history: + tags: + - Bugs + "/bug/{id}/history": get: - tags: [Bugs] summary: Get the history of changes for a specific bug description: | Gets the history of changes for a particular bug in the database. You can specify a bug ID or alias and, optionally, a datetime timestamp to only show history since that date. @@ -242,7 +234,7 @@ paths: type: string format: date-time responses: - 200: + "200": description: A list of bugs with their history content: application/json: @@ -259,19 +251,19 @@ paths: alias: null history: - when: "2014-09-23T19:12:17Z" - who: "user@bugzilla.org" + who: user@bugzilla.org changes: - - field_name: "priority" - added: "P1" - removed: "P2" - - field_name: "severity" - added: "critical" - removed: "blocker" + - field_name: priority + added: P1 + removed: P2 + - field_name: severity + added: critical + removed: blocker - when: "2014-09-28T21:03:47Z" - who: "user@bugzilla.org" + who: user@bugzilla.org changes: - - field_name: "flagtypes.name" - added: "blocker?" + - field_name: flagtypes.name + added: blocker? removed: "" default: description: | @@ -280,10 +272,10 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - + tags: + - Bugs /bug: get: - tags: [Bugs] summary: Search for bugs based on particular criteria description: | Allows you to search for bugs based on specific criteria. Bugs are returned if they match the criteria specified. Criteria are joined in a logical AND, meaning bugs returned must match all of the specified criteria. @@ -305,7 +297,7 @@ paths: type: string - name: count_only in: query - description: If set to true, an object with a single key called "bug_count" will be returned, which is the number of bugs that matched the search. + description: 'If set to true, an object with a single key called "bug_count" will be returned, which is the number of bugs that matched the search.' schema: type: boolean - name: creation_time @@ -352,7 +344,7 @@ paths: type: integer - name: offset in: query - description: Used in conjunction with the limit argument, offset defines the starting position for the search. + description: "Used in conjunction with the limit argument, offset defines the starting position for the search." schema: type: integer - name: op_sys @@ -392,7 +384,7 @@ paths: type: string - name: status in: query - description: The current status of a bug (not including its resolution, if it has one, which is a separate field above). + description: "The current status of a bug (not including its resolution, if it has one, which is a separate field above)." schema: type: string - name: summary @@ -441,7 +433,7 @@ paths: schema: type: string responses: - 200: + "200": description: A list of bugs matching the search criteria content: application/json: @@ -456,26 +448,26 @@ paths: bugs: - id: 35 alias: null - assigned_to: "user@bugzilla.org" - component: "Widgets" + assigned_to: user@bugzilla.org + component: Widgets creation_time: "2014-09-23T19:12:17Z" - creator: "user@bugzilla.org" - description: "Bug description goes here." - filed_via: "REST API" + creator: user@bugzilla.org + description: Bug description goes here. + filed_via: REST API last_change_time: "2014-09-28T21:03:47Z" - op_sys: "All" - platform: "All" - priority: "P1" - product: "MyProduct" + op_sys: All + platform: All + priority: P1 + product: MyProduct resolution: null - severity: "critical" - status: "NEW" - summary: "Bug summary goes here." + severity: critical + status: NEW + summary: Bug summary goes here. tags: null target_milestone: "---" qa_contact: null triage_owner: null - type: "defect" + type: defect url: null version: null whiteboard: null @@ -489,9 +481,9 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - + tags: + - Bugs post: - tags: [Bugs] summary: Create a new bug description: | This endpoint allows you to create a new bug in Bugzilla. If you specify any @@ -513,7 +505,7 @@ paths: product: TestProduct component: TestComponent version: unspecified - summary: "This is a test bug - please disregard" + summary: This is a test bug - please disregard alias: SomeAlias op_sys: All priority: P1 @@ -528,11 +520,10 @@ paths: type: object properties: id: - type: integer description: This is the ID of the newly-filed bug. + type: integer example: id: 12345 - default: description: | Various error responses, including: @@ -568,12 +559,12 @@ paths: * 504 (Invalid User) Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details. deprecated: false - - /bug/{bug_id}/graph: + tags: + - Bugs + "/bug/{bug_id}/graph": get: - tags: [Bugs] summary: Return a graph of bug relationships - description: Return a graph of bug relationships such as dependencies, regressions, and duplicates. By default, resolved bugs are not returned but can be if needed. The bug ID provided will be the root node of the graph. + description: "Return a graph of bug relationships such as dependencies, regressions, and duplicates. By default, resolved bugs are not returned but can be if needed. The bug ID provided will be the root node of the graph." parameters: - name: bug_id in: path @@ -602,13 +593,16 @@ paths: default: false - name: relationship in: query - description: One of "dependencies", "duplicates", or "regressions". + description: 'One of "dependencies", "duplicates", or "regressions".' schema: type: string - default: "dependencies" - enum: ["dependencies", "duplicates", "regressions"] + default: dependencies + enum: + - dependencies + - duplicates + - regressions responses: - 200: + "200": description: | A graph of bug relationships @@ -635,23 +629,22 @@ paths: $ref: "#/components/schemas/BugNode" dupe: $ref: "#/components/schemas/BugNode" - example: blocked: - 2: - 3: + "2": + "3": bug: alias: null id: 3 is_confirmed: 1 op_sys: Unspecified platform: Unspecified - priority: -- + priority: "--" resolution: "" severity: normal status: NEW summary: Another new test bug - target_milestone: --- + target_milestone: "---" type: defect url: "" version: unspecified @@ -662,12 +655,12 @@ paths: is_confirmed: 1 op_sys: Unspecified platform: Unspecified - priority: -- + priority: "--" resolution: "" severity: normal status: NEW summary: this is a new test bug - target_milestone: --- + target_milestone: "---" type: defect url: "" version: unspecified @@ -678,12 +671,12 @@ paths: is_confirmed: 1 op_sys: Unspecified platform: Unspecified - priority: -- + priority: "--" resolution: "" severity: normal status: NEW summary: This is a new test bug - target_milestone: --- + target_milestone: "---" type: defect url: "" version: unspecified @@ -695,10 +688,10 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - + tags: + - Bugs /bug/possible_duplicates: get: - tags: [Bugs] summary: Gets a list of possible duplicate bugs description: | Gets a list of possible duplicate bugs based on a given bug ID or bug summary. @@ -710,7 +703,7 @@ paths: type: integer - name: summary in: query - description: A summary to search for duplicates of, only used if no bug ID is given. + description: "A summary to search for duplicates of, only used if no bug ID is given." schema: type: string - name: product @@ -727,7 +720,7 @@ paths: schema: type: integer responses: - 200: + "200": description: A list of possible duplicate bugs content: application/json: @@ -747,24 +740,23 @@ paths: who: user@bugzilla.org changes: - field_name: priority - added: "P1" - removed: "P2" + added: P1 + removed: P2 - field_name: severity - added: "critical" - removed: "blocker" + added: critical + removed: blocker - when: "2014-09-28T21:03:47Z" who: user@bugzilla.org changes: - field_name: flagtypes.name - added: "blocker?" + added: blocker? removed: "" default: description: Various error responses - - # Comments - /bug/{id_or_alias}/comment: + tags: + - Bugs + "/bug/{id_or_alias}/comment": get: - tags: [Comments] summary: Get all comments for a bug description: This allows you to get all comments for a particular bug using the bug ID or alias. parameters: @@ -778,12 +770,12 @@ paths: - integer - name: new_since in: query - description: If specified, the method will only return comments newer than this time. + description: "If specified, the method will only return comments newer than this time." schema: type: string format: date-time responses: - 200: + "200": description: A list of Comments content: application/json: @@ -805,10 +797,10 @@ paths: type: object example: bugs: - 35: + "35": comments: - time: "2000-07-25T13:50:04Z" - text: "test bug to fix problem in removing from cc list." + text: test bug to fix problem in removing from cc list. bug_id: 35 count: 0 attachment_id: null @@ -817,7 +809,6 @@ paths: creator: user@bugzilla.org creation_time: "2000-07-25T13:50:04Z" id: 75 - comments: {} default: description: | @@ -829,15 +820,14 @@ paths: The bug_id you specified doesn't exist in the database. * 102 (Access Denied) You do not have access to the bug_id you specified. - content: application/json: schema: $ref: "#/components/schemas/Error" - - /bug/comment/{comment_id}: + tags: + - Comments + "/bug/comment/{comment_id}": get: - tags: [Comments] summary: Get a specific comment description: This allows you to get a specific comment based on the comment ID parameters: @@ -848,7 +838,7 @@ paths: schema: type: integer responses: - 200: + "200": description: A single Comment content: application/json: @@ -856,7 +846,7 @@ paths: type: object properties: comments: - description: This is an object, where the keys are the numeric IDs of the bugs, and the value is a object with a single key, comments, which is an array of comments. + description: "This is an object, where the keys are the numeric IDs of the bugs, and the value is a object with a single key, comments, which is an array of comments." type: object additionalProperties: $ref: "#/components/schemas/Comment" @@ -864,9 +854,9 @@ paths: type: object example: comments: - 75: + "75": time: "2000-07-25T13:50:04Z" - text: "test bug to fix problem in removing from cc list." + text: test bug to fix problem in removing from cc list. bug_id: 35 count: 0 attachment_id: null @@ -888,10 +878,10 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - - /bug/{id}/comment: + tags: + - Comments + "/bug/{id}/comment": post: - tags: [Comments] summary: Create a comment on a bug description: This allows you to add a comment to a bug in Bugzilla. All comments created via the API will be considered Markdown (specifically GitHub Flavored Markdown). parameters: @@ -916,31 +906,30 @@ paths: items: type: integer comment: - description: The comment to append to the bug. If this is empty or all whitespace, an error will be thrown. + description: "The comment to append to the bug. If this is empty or all whitespace, an error will be thrown." type: string is_private: - description: If set to true, the comment is private, otherwise it is assumed to be public. + description: "If set to true, the comment is private, otherwise it is assumed to be public." type: boolean is_markdown: description: "If true, the comment will be rendered as markdown. (default: ``false``)" type: boolean work_time: - description: Adds this many hours to the "Hours Worked" on the bug. If you are not in the time tracking group, this value will be ignored. + description: 'Adds this many hours to the "Hours Worked" on the bug. If you are not in the time tracking group, this value will be ignored.' type: number + additionalProperties: false required: - comment - additionalProperties: false example: ids: - 123 - 456 - comment: "This is an additional comment" + comment: This is an additional comment is_private: false is_markdown: true work_time: 2.5 - responses: - 200: + "200": description: ID of the newly-created comment content: application/json: @@ -966,10 +955,10 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - - /bug/comment/tags/{query}: + tags: + - Comments + "/bug/comment/tags/{query}": get: - tags: [Comments] summary: Search for comment tags description: Searches for tags which contain the provided substring. parameters: @@ -981,12 +970,12 @@ paths: type: string - name: limit in: query - description: If provided, will return no more than "limit" tags. Defaults to "10". + description: 'If provided, will return no more than "limit" tags. Defaults to "10".' schema: type: integer default: 10 responses: - 200: + "200": description: An array of matching tags content: application/json: @@ -995,7 +984,7 @@ paths: items: type: string example: - - "spam" + - spam default: description: | Various error responses, including: @@ -1005,10 +994,10 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - - /bug/comment/{comment_id}/tags: + tags: + - Comments + "/bug/comment/{comment_id}/tags": put: - tags: [Comments] summary: Update tags for a comment description: Adds or removes tags from a comment. parameters: @@ -1036,19 +1025,15 @@ paths: type: array items: type: string - # QUESTION: should the parameter be in the body? - # https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html#update-comment-tags + additionalProperties: false required: - comment_id - additionalProperties: false example: - # comment_id: 75 add: - - "spam" - - "bad" - + - spam + - bad responses: - 200: + "200": description: An array of strings containing the comment's updated tags. content: application/json: @@ -1057,8 +1042,8 @@ paths: items: type: string example: - - "bad" - - "spam" + - bad + - spam default: description: | Various error responses, including: @@ -1071,10 +1056,10 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - + tags: + - Comments /bug/comment/render: post: - tags: [Comments] summary: Render comment as HTML description: Returns the HTML rendering of the provided comment text. requestBody: @@ -1090,14 +1075,14 @@ paths: id: description: The ID of the bug to render the comment against. type: integer + additionalProperties: false required: - text - additionalProperties: false example: - text: "This issue has been fixed in bug 1234." + text: This issue has been fixed in bug 1234. id: 2345 responses: - 200: + "200": description: Text containing the HTML rendering content: application/json: @@ -1107,7 +1092,7 @@ paths: html: type: string example: - html: 'This issue has been fixed in bug 1234.' + html: This issue has been fixed in bug 1234. default: description: | Various error responses, including those thrown by :ref:`rest_single_bug`. @@ -1115,7 +1100,8 @@ paths: application/json: schema: $ref: "#/components/schemas/Error" - + tags: + - Comments components: schemas: Bug: @@ -1163,7 +1149,7 @@ components: creator_detail: $ref: "#/components/schemas/User" deadline: - description: The day that this bug is due to be completed, in the format YYYY-MM-DD. + description: "The day that this bug is due to be completed, in the format YYYY-MM-DD." type: string depends_on: description: The IDs of bugs that this bug "depends on". @@ -1171,7 +1157,7 @@ components: items: type: integer dupe_of: - description: The bug ID of the bug that this bug is a duplicate of. If this bug isn't a duplicate of any bug, this will be null. + description: "The bug ID of the bug that this bug is a duplicate of. If this bug isn't a duplicate of any bug, this will be null." type: integer duplicates: description: The ids of bugs that are marked as duplicate of this bug. @@ -1195,13 +1181,13 @@ components: description: The unique numeric ID of this bug. type: integer is_cc_accessible: - description: If true, this bug can be accessed by members of the CC list, even if they are not in the groups the bug is restricted to. + description: "If true, this bug can be accessed by members of the CC list, even if they are not in the groups the bug is restricted to." type: boolean is_confirmed: description: true if the bug has been confirmed. Usually this means that the bug has at some point been moved out of the UNCONFIRMED status and into another open status. type: boolean is_creator_accessible: - description: If true, this bug can be accessed by the creator of the bug, even if they are not a member of the groups the bug is restricted to. + description: "If true, this bug can be accessed by the creator of the bug, even if they are not a member of the groups the bug is restricted to." type: boolean keywords: description: Each keyword that is on this bug. @@ -1243,7 +1229,7 @@ components: description: The number of hours of work remaining until work on this bug is complete. type: number resolution: - description: The current resolution of the bug, or an empty string if the bug is open. + description: "The current resolution of the bug, or an empty string if the bug is open." type: string see_also: description: The URLs in the See Also field on the bug. @@ -1260,7 +1246,7 @@ components: description: The summary of this bug. type: string target_milestone: - description: The milestone that this bug is supposed to be fixed by, or for closed bugs, the milestone that it was fixed for. + description: "The milestone that this bug is supposed to be fixed by, or for closed bugs, the milestone that it was fixed for." type: string type: description: The type of the bug. @@ -1269,7 +1255,7 @@ components: description: The token that you would have to pass to the process_bug.cgi page in order to update this bug. This changes every time the bug is updated. This field is not returned to logged-out users. type: string url: - description: A URL that demonstrates the problem described in the bug, or is somehow related to the bug report. + description: "A URL that demonstrates the problem described in the bug, or is somehow related to the bug report." type: string version: description: The version the bug was reported against. @@ -1277,9 +1263,6 @@ components: whiteboard: description: The value of the "status whiteboard" field on the bug. type: string - # Custom fields? - # Extra fields? - Flag: type: object properties: @@ -1307,9 +1290,8 @@ components: description: The login name of the user who created or last modified the flag. type: string requestee: - description: The login name of the user this flag has been requested to be granted or denied. Note, this field is only returned if a requestee is set. + description: "The login name of the user this flag has been requested to be granted or denied. Note, this field is only returned if a requestee is set." type: string - User: type: object properties: @@ -1317,18 +1299,17 @@ components: description: The user ID for this user. type: integer real_name: - description: The 'real' name for this user, if any. + description: "The 'real' name for this user, if any." type: string nick: - description: The user's nickname. Currently, this is extracted from the real_name, name, or email field. + description: "The user's nickname. Currently, this is extracted from the real_name, name, or email field." type: string name: description: The user's Bugzilla login. type: string email: - description: The user's email address. Currently, this is the same value as the name. + description: "The user's email address. Currently, this is the same value as the name." type: string - BugWithHistory: type: object properties: @@ -1343,7 +1324,6 @@ components: type: array items: $ref: "#/components/schemas/History" - History: type: object properties: @@ -1359,7 +1339,6 @@ components: type: array items: $ref: "#/components/schemas/Change" - Change: type: object properties: @@ -1373,268 +1352,262 @@ components: description: The new value of the bug field which has been added by the change. type: string attachment_id: - description: The ID of the attachment that was changed. This only appears if the change was to an attachment, otherwise `attachment_id` will not be present in this object. + description: "The ID of the attachment that was changed. This only appears if the change was to an attachment, otherwise `attachment_id` will not be present in this object." type: integer nullable: true - NewBug: type: object properties: product: - type: string description: The name of the product the bug is being filed against. - component: type: string + component: description: The name of a component in the product above. - summary: type: string + summary: description: A brief description of the bug being filed. - version: type: string + version: description: A version of the product above; the version the bug was found in. - description: type: string + description: description: (defaulted) The description (initial comment) of the bug. Some Bugzilla installations require this to not be blank. - filed_via: type: string + filed_via: description: (defaulted) How the bug is being filed. It will be ``api`` by default when filing through the API. - op_sys: type: string + op_sys: description: (defaulted) The operating system the bug was discovered on. - platform: type: string + platform: description: (defaulted) What type of hardware the bug was experienced on. + type: string priority: + description: "(defaulted) What order the bug will be fixed in by the developer, compared to the developer's other bugs." type: string - description: (defaulted) What order the bug will be fixed in by the developer, compared to the developer's other bugs. severity: - type: string description: (defaulted) How severe the bug is. - type: type: string + type: description: The basic category of the bug. Some Bugzilla installations require this to be specified. - alias: type: string + alias: description: The alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla. + type: string assigned_to: + description: "A user to assign this bug to, if you don't want it to be assigned to the component owner." type: string - description: A user to assign this bug to, if you don't want it to be assigned to the component owner. cc: + description: An array of usernames to CC on this bug. type: array items: type: string - description: An array of usernames to CC on this bug. comment_is_private: + description: "If set to true, the description is private, otherwise it is assumed to be public." type: boolean - description: If set to true, the description is private, otherwise it is assumed to be public. groups: + description: 'An array of group names to put this bug into. You can see valid group names on the Permissions tab of the Preferences screen, or, if you are an administrator, in the Groups control panel. If you don''t specify this argument, then the bug will be added into all the groups that are set as being "Default" for this product. (If you want to avoid that, you should specify ``groups`` as an empty array.)' type: array items: type: string - description: An array of group names to put this bug into. You can see valid group names on the Permissions tab of the Preferences screen, or, if you are an administrator, in the Groups control panel. If you don't specify this argument, then the bug will be added into all the groups that are set as being "Default" for this product. (If you want to avoid that, you should specify ``groups`` as an empty array.) qa_contact: + description: "If this installation has QA Contacts enabled, you can set the QA Contact here if you don't want to use the component's default QA Contact." type: string - description: If this installation has QA Contacts enabled, you can set the QA Contact here if you don't want to use the component's default QA Contact. status: - type: string description: The status that this bug should start out as. Note that only certain statuses can be set on bug creation. + type: string resolution: + description: "If you are filing a closed bug, then you will have to specify a resolution. You cannot currently specify a resolution of ``DUPLICATE`` for new bugs, though. That must be done with :ref:`rest_update_bug`." type: string - description: If you are filing a closed bug, then you will have to specify a resolution. You cannot currently specify a resolution of ``DUPLICATE`` for new bugs, though. That must be done with :ref:`rest_update_bug`. target_milestone: - type: string description: A valid target milestone for this product. + type: string flags: type: array items: $ref: "#/components/schemas/NewFlag" keywords: + description: One or more valid keywords to add to this bug. type: array items: type: string - description: One or more valid keywords to add to this bug. dependson: + description: One or more valid bug ids that this bug depends on. type: array items: type: integer - description: One or more valid bug ids that this bug depends on. blocked: + description: One or more valid bug ids that this bug blocks. type: array items: type: integer - description: One or more valid bug ids that this bug blocks. regressed_by: + description: One or more valid bug ids that introduced this bug. type: array items: type: integer - description: One or more valid bug ids that introduced this bug. required: - product - component - summary - version - type - NewFlag: type: object properties: name: - type: string description: The name of the flag type. + type: string type_id: - type: integer description: The internal flag type ID. + type: integer status: + description: 'The flags new status (i.e. "?", "+", "-" or "X" to clear flag).' type: string - description: The flags new status (i.e. "?", "+", "-" or "X" to clear flag). requestee: - type: string description: The login of the requestee if the flag type is requestable to a specific user. - + type: string BugUpdate: type: object - required: - - ids properties: ids: + description: The IDs or aliases of the bugs that you want to modify. type: array items: type: - integer - string - description: The IDs or aliases of the bugs that you want to modify. alias: - type: string description: The alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla. - assigned_to: type: string + assigned_to: description: The full login name of the user this bug is assigned to. + type: string blocks: - type: object description: Bugs that this bug blocks. + type: object $ref: "#/components/schemas/BugRelationship" depends_on: - type: object description: Bugs that this bug depends on. + type: object $ref: "#/components/schemas/BugRelationship" regressions: - type: object description: Bugs that this bug regresses. + type: object $ref: "#/components/schemas/BugRelationship" regressed_by: - type: object description: Bugs that regress this bug. + type: object $ref: "#/components/schemas/BugRelationship" cc: + description: The users on the cc list. type: object properties: add: + description: "User names to add to the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name." type: array items: type: string - description: User names to add to the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name. remove: + description: "User names to remove from the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name." type: array items: type: string - description: User names to remove from the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name. - description: The users on the cc list. is_cc_accessible: - type: boolean description: Whether or not users in the CC list are allowed to access the bug. + type: boolean comment: + description: A comment on the change. type: object properties: body: - type: string description: The actual text of the comment. - comment: type: string + comment: description: An alias for the comment body. (For compatibility with the parameters to rest_add_comment) + type: string is_private: + description: "Whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown." type: boolean - description: Whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown. - description: A comment on the change. comment_is_private: - type: object description: | This is how you update the privacy of comments that are already on a bug. This is a object, where the keys are the ID of comments. The comment IDs must be valid for the bug being updated. Thus, it is not practical to use this while updating multiple bugs at once, as a single comment ID will never be valid on multiple bugs. + type: object additionalProperties: type: boolean description: Specifies whether that comment should become private (`true`) or public (`false`). component: - type: string description: The Component the bug is in. + type: string deadline: + description: The Deadline field is a date specifying when the bug must be completed by. type: string format: date - description: The Deadline field is a date specifying when the bug must be completed by. dupe_of: - type: integer description: | The bug that this bug is a duplicate of. If you want to mark a bug as a duplicate, the safest thing to do is to set this value and not set the status or resolution fields. They will automatically be set by Bugzilla to the appropriate values for duplicate bugs. + type: integer estimated_time: + description: "The total estimate of time required to fix the bug, in hours." type: number - description: The total estimate of time required to fix the bug, in hours. flags: - type: array - items: - $ref: "#/components/schemas/FlagChange" description: | An array of Flag change objects. Of any item, at least the status and one of type_id, id, or name must be specified. If a type_id or name matches a single currently set flag, the flag will be updated unless new is specified. + type: array + items: + $ref: "#/components/schemas/FlagChange" groups: + description: The groups a bug is in. type: object properties: add: + description: | + The names of groups to add. Passing in an invalid group name or a group that you cannot add to this bug will cause an error to be thrown. type: array items: type: string - description: | - The names of groups to add. Passing in an invalid group name or a group that you cannot add to this bug will cause an error to be thrown. remove: + description: The names of groups to remove. Passing in an invalid group name or a group that you cannot remove from this bug will cause an error to be thrown. type: array items: type: string - description: The names of groups to remove. Passing in an invalid group name or a group that you cannot remove from this bug will cause an error to be thrown. - description: The groups a bug is in. keywords: + description: Keywords on the bug. type: object properties: add: + description: The names of keywords to add to the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. type: array items: type: string - description: The names of keywords to add to the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. remove: + description: The names of keywords to remove from the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. type: array items: type: string - description: The names of keywords to remove from the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. set: + description: "An exact set of keywords to set the field to, on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. Specifying `set` overrides `add` and `remove`." type: array items: type: string - description: An exact set of keywords to set the field to, on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. Specifying `set` overrides `add` and `remove`. - description: Keywords on the bug. op_sys: - type: string description: The Operating System ("OS") field on the bug. - platform: type: string + platform: description: The Platform or "Hardware" field on the bug. - priority: type: string + priority: description: The Priority field on the bug. - product: type: string + product: description: | The name of the product that the bug is in. If you change this, you will probably also want to @@ -1659,163 +1632,142 @@ components: Users can only move a bug into a product if they would normally have permission to file new bugs in that product. - qa_contact: type: string + qa_contact: description: The full login name of the bug's QA Contact. + type: string is_creator_accessible: - type: boolean description: Whether or not the bug's reporter is allowed to access the bug. + type: boolean remaining_time: - type: number description: | How much work time is remaining to fix the bug, in hours. If you set ``work_time`` but don't explicitly set ``remaining_time``, then the ``work_time`` will be deducted from the bug's ``remaining_time``. + type: number reset_assigned_to: + description: "If true, the `assigned_to` field will be reset to the default for the component that the bug is in. (If you have set the component at the same time as using this, then the component used will be the new component, not the old one.)" type: boolean - description: - If true, the `assigned_to` field will be reset to the default for the component that the bug is in. (If you have set the component at the - same time as using this, then the component used - will be the new component, not the old one.) reset_qa_contact: + description: "If true, the `qa_contact` field will be reset to the default for the component that the bug is in." type: boolean - description: If true, the `qa_contact` field will be reset to the default for the component that the bug is in. resolution: + description: |- + The current resolution. May only be set if you are closing a bug or if you are modifying an already-closed bug. Attempting to set the resolution to *any* value (even an empty or null string) on an open bug will cause an error to be thrown. + > **Note:** If you change the ``status`` field to an open status, the resolution field will automatically be cleared, so you don't have to clear it manually. type: string - description: The current resolution. May only be set if you - are closing a bug or if you are modifying an - already-closed bug. Attempting to set the - resolution to *any* value (even an empty or null - string) on an open bug will cause an error to be - thrown. - - > **Note:** - If you change the ``status`` field to an open - status, the resolution field will automatically - be cleared, so you don't have to clear it - manually. see_also: + description: "The See Also field on a bug, specifying URLs to bugs in other bug trackers." type: object properties: add: + description: "URLs to add to the field. Each URL must be a valid URL to a bug-tracker, or an error will be thrown." type: array items: type: string - description: URLs to add to the field. Each - URL must be a valid URL to a bug-tracker, or - an error will be thrown. remove: + description: URLs to remove from the field. Invalid URLs will be ignored. type: array items: type: string - description: URLs to remove from the - field. Invalid URLs will be ignored. - description: The See Also field on a bug, specifying URLs to bugs in other bug trackers. severity: - type: string description: The Severity field of a bug. + type: string status: + description: "The status you want to change the bug to. Note that if a bug is changing from open to closed, you should also specify a `resolution`." type: string - description: The status you want to change the bug to. Note that if a bug is changing from open to closed, you should also specify a `resolution`. summary: - type: string description: The Summary field of the bug. - target_milestone: type: string + target_milestone: description: The bug's Target Milestone. - type: type: string + type: description: The Type field on the bug. - url: type: string + url: description: The "URL" field of a bug. - version: type: string + version: description: The bug's Version field. - whiteboard: type: string + whiteboard: description: The Status Whiteboard field of a bug. + type: string work_time: + description: "The number of hours worked on this bug as part of this change. If you set ``work_time`` but don't explicitly set ``remaining_time``, then the ``work_time`` will be deducted from the bug's ``remaining_time``." type: number - description: The number of hours worked on this bug as part - of this change. - If you set ``work_time`` but don't explicitly - set ``remaining_time``, then the ``work_time`` - will be deducted from the bug's ``remaining_time``. - + required: + - ids BugRelationship: type: object properties: add: + description: Bug IDs to add to this field. type: array items: type: integer - description: Bug IDs to add to this field. remove: + description: "Bug IDs to remove from this field. If the bug IDs are not already in the field, they will be ignored." type: array items: type: integer - description: Bug IDs to remove from this field. If the bug IDs are not already in the field, they will be ignored. set: + description: "An exact set of bug IDs to set this field to, overriding the current value. If you specify `set`, then `add` and `remove` will be ignored." type: array items: type: integer - description: An exact set of bug IDs to set this field to, overriding the current value. If you specify `set`, then `add` and `remove` will be ignored. - FlagChange: type: object properties: name: - type: string description: The name of the flag that will be created or updated. + type: string type_id: - type: integer description: The internal flag type ID that will be created or updated. + type: integer status: + description: 'The flags new status (i.e. "?", "+", "-" or "X" to clear a flag).' type: string - description: The flags new status (i.e. "?", "+", "-" or "X" to clear a flag). requestee: - type: string description: The login of the requestee if the flag type is requestable to a specific user. + type: string id: - type: integer description: Use ID to specify the flag to be updated. + type: integer new: - type: boolean description: Set to true if you specifically want a new flag to be created. + type: boolean required: - status - UpdatedBug: type: object properties: id: - type: integer description: The ID of the bug that was updated. + type: integer alias: + description: "The alias of the bug that was updated, if this bug has any alias." type: string - description: The alias of the bug that was updated, if this bug has any alias. last_change_time: + description: "The exact time that this update was done at, for this bug." type: string format: date-time - description: The exact time that this update was done at, for this bug. changes: type: object additionalProperties: $ref: "#/components/schemas/FieldChange" - FieldChange: type: object properties: added: + description: "The values that were added to this field, possibly a comma-and-space-separated list if multiple values were added." type: string - description: The values that were added to this field, possibly a comma-and-space-separated list if multiple values were added. removed: + description: "The values that were removed from this field, possibly a comma-and-space-separated list if multiple values were removed." type: string - description: The values that were removed from this field, possibly a comma-and-space-separated list if multiple values were removed. - BugNode: type: object properties: @@ -1823,7 +1775,6 @@ components: $ref: "#/components/schemas/Bug" additionalProperties: $ref: "#/components/schemas/BugNode" - Comment: type: object properties: @@ -1834,15 +1785,15 @@ components: description: The ID of the bug that this comment is on. type: integer attachment_id: - description: If the comment was made on an attachment, this will be the ID of that attachment. Otherwise it will be null. + description: "If the comment was made on an attachment, this will be the ID of that attachment. Otherwise it will be null." type: - integer - null count: - description: The number of the comment local to the bug. The Description is 0, comments start with 1. + description: "The number of the comment local to the bug. The Description is 0, comments start with 1." type: integer text: - description: The body of the comment, including any special text (such as “this bug was marked as a duplicate of…”). + description: "The body of the comment, including any special text (such as “this bug was marked as a duplicate of…”)." type: string raw_text: description: The body of the comment without any special additional text. @@ -1872,59 +1823,57 @@ components: is_markdown: description: '``true`` if this comment is private (only visible to a certain group called the "insidergroup"), ``false``' type: boolean - Error: type: object properties: error: - description: When an error occurs over REST, an object is returned with the key error set to true. + description: "When an error occurs over REST, an object is returned with the key error set to true." const: true message: type: string code: type: integer - tags: - name: Attachments - description: The Bugzilla API for creating, changing, and getting the details of attachments. + description: "The Bugzilla API for creating, changing, and getting the details of attachments." externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/attachment.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/attachment.html" - name: Bugs description: This part of the Bugzilla REST API allows you to file new bugs in Bugzilla and to get information about existing bugs. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/bug.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/bug.html" - name: Bug User Last Visited description: Update the last-visited time for the specified bug and current user. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/bug-user-last-visit.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/bug-user-last-visit.html" - name: Bugzilla Information description: These methods are used to get general configuration information about this Bugzilla instance. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/bugzilla.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/bugzilla.html" - name: Classifications description: This part of the Bugzilla API allows you to deal with the available classifications. You will be able to get information about them as well as manipulate them. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/classification.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/classification.html" - name: Comments - description: This allows you to get data about comments, given a bug ID or comment ID. + description: "This allows you to get data about comments, given a bug ID or comment ID." externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html" - name: Components description: This part of the Bugzilla API looks at individual components and also allows updating their information. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/component.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/component.html" - name: Bug Fields description: The Bugzilla API for getting details about bug fields. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/field.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/field.html" - name: Flag Activity description: This API provides information about activity relating to bug and attachment flags. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/flag-activity.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/flag-activity.html" - name: General description: This is the standard REST API for external programs that want to interact with Bugzilla. It provides a REST interface to various Bugzilla functions. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/general.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/general.html" - name: Github description: | This API endpoint is for creating attachments in a bug that are redirect links to a @@ -1953,24 +1902,23 @@ tags: make sure the title is formatted correctly to allow the bug id to be determined. Examples are: ``Bug 1234:``, ``Bug - 1234``, ``bug 1234``, or ``Bug 1234 -``. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/github.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/github.html" - name: Groups - description: The API for creating, changing, and getting information about groups. + description: "The API for creating, changing, and getting information about groups." externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/group.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/group.html" - name: Products description: This part of the Bugzilla API allows you to list the available products and get information about them. externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/product.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/product.html" - name: Users - description: This part of the Bugzilla API allows you to create user accounts, get information about user accounts and to log in or out using an existing account. + description: "This part of the Bugzilla API allows you to create user accounts, get information about user accounts and to log in or out using an existing account." externalDocs: - url: https://bmo.readthedocs.io/en/latest/api/core/v1/user.html + url: "https://bmo.readthedocs.io/en/latest/api/core/v1/user.html" - name: Webhooks description: These methods are used to access information about and update your configured webhooks. externalDocs: - url: https://bmo.readthedocs.io/en/latest/extensions/Webhooks/api/v1/webhooks.html#list - + url: "https://bmo.readthedocs.io/en/latest/extensions/Webhooks/api/v1/webhooks.html#list" externalDocs: description: Sphinx WebService API Reference - url: https://bugzilla.readthedocs.io/en/latest/api/ + url: "https://bugzilla.readthedocs.io/en/latest/api/" From c3c2f2234c788c821426aa614aa90ce7b4a4398c Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 09:59:18 +0100 Subject: [PATCH 16/29] Added parameter component "BugIdOrAlias" for re usability. --- openapi.yaml | 52 +++++++++++++++------------------------------------- 1 file changed, 15 insertions(+), 37 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index f4f36e588b..b781d88abf 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17,14 +17,7 @@ paths: summary: Get information about a bug description: Gets information about a particular bug using its ID or alias. parameters: - - name: id_or_alias - in: path - description: An integer bug ID or a bug alias string. - required: true - schema: - type: - - string - - integer + - $ref: "#/components/parameters/BugIdOrAlias" responses: "200": description: A list of Bugs @@ -136,11 +129,7 @@ paths: description: | Allows you to update the fields of a bug. Automatically sends emails out about the changes. parameters: - - name: id_or_alias - in: path - description: An integer bug ID or alias. - schema: - type: string + - $ref: "#/components/parameters/BugIdOrAlias" requestBody: content: application/json: @@ -219,14 +208,7 @@ paths: description: | Gets the history of changes for a particular bug in the database. You can specify a bug ID or alias and, optionally, a datetime timestamp to only show history since that date. parameters: - - name: id - in: path - description: An integer bug ID or alias. - required: true - schema: - type: - - string - - integer + - $ref: "#/components/parameters/BugIdOrAlias" - name: new_since in: query description: A datetime timestamp to only show history since. @@ -760,14 +742,7 @@ paths: summary: Get all comments for a bug description: This allows you to get all comments for a particular bug using the bug ID or alias. parameters: - - name: id_or_alias - in: path - description: A single integer bug ID or alias. - required: true - schema: - type: - - string - - integer + - $ref: "#/components/parameters/BugIdOrAlias" - name: new_since in: query description: "If specified, the method will only return comments newer than this time." @@ -885,14 +860,7 @@ paths: summary: Create a comment on a bug description: This allows you to add a comment to a bug in Bugzilla. All comments created via the API will be considered Markdown (specifically GitHub Flavored Markdown). parameters: - - name: id - in: path - description: The ID or alias of the bug to append a comment to. - required: true - schema: - type: - - string - - integer + - $ref: "#/components/parameters/BugIdOrAlias" requestBody: required: true content: @@ -1103,6 +1071,16 @@ paths: tags: - Comments components: + parameters: + BugIdOrAlias: + name: id_or_alias + in: path + description: A single integer bug ID or alias. + required: true + schema: + type: + - string + - integer schemas: Bug: type: object From 56185672a0b100c42dbea15c5de0fb73feb754c4 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 10:49:04 +0100 Subject: [PATCH 17/29] Aligned "Comments" section --- openapi.yaml | 53 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index b781d88abf..51f6c17eb6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -843,12 +843,17 @@ paths: bugs: {} default: description: | - Various error responses, including: + This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). In addition, it can also throw the following errors: - * 110 (Comment Is Private) - You specified the id of a private comment in the “comment_ids” argument, and you are not in the “insider group” that can see private comments. + * 110 (Comment Is Private) + You specified the id of a private comment in the "comment_ids" + argument, and you are not in the "insider group" that can see + private comments. * 111 (Invalid Comment ID) - You specified an id in the “comment_ids” argument that is invalid–either you specified something that wasn’t a number, or there is no comment with that id. + You specified an id in the "comment_ids" argument that is invalid--either + you specified something that wasn't a number, or there is no comment with + that id. + content: application/json: schema: @@ -874,14 +879,15 @@ paths: items: type: integer comment: - description: "The comment to append to the bug. If this is empty or all whitespace, an error will be thrown." + description: "The comment to append to the bug. If this is empty or all whitespace, an error will be thrown saying that you did not set the ``comment`` parameter." type: string is_private: description: "If set to true, the comment is private, otherwise it is assumed to be public." type: boolean is_markdown: - description: "If true, the comment will be rendered as markdown. (default: ``false``)" + description: "If true, the comment will be rendered as markdown." type: boolean + default: false work_time: description: 'Adds this many hours to the "Hours Worked" on the bug. If you are not in the time tracking group, this value will be ignored.' type: number @@ -913,12 +919,22 @@ paths: Various error responses, including: * 54 (Hours Worked Too Large) + You specified a "work_time" larger than the maximum allowed value of + "99999.99". * 100 (Invalid Bug Alias) + If you specified an alias and there is no bug with that alias. * 101 (Invalid Bug ID) + The id you specified doesn't exist in the database. * 109 (Bug Edit Denied) + You did not have the necessary rights to edit the bug. * 113 (Can't Make Private Comments) + You tried to add a private comment, but don't have the necessary rights. * 114 (Comment Too Long) + You tried to add a comment longer than the maximum allowed length + (65,535 characters). * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag to true but the Markdown feature + is not enabled. content: application/json: schema: @@ -938,7 +954,7 @@ paths: type: string - name: limit in: query - description: 'If provided, will return no more than "limit" tags. Defaults to "10".' + description: "If provided, will return no more than `limit` tags." schema: type: integer default: 10 @@ -955,9 +971,10 @@ paths: - spam default: description: | - Various error responses, including: + This method can throw all of the errors that [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) throws, plus: * 125 (Comment Tagging Disabled) + Comment tagging support is not available or enabled. content: application/json: schema: @@ -1014,12 +1031,16 @@ paths: - spam default: description: | - Various error responses, including: + This method can throw all of the errors that [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) throws, plus: * 125 (Comment Tagging Disabled) + Comment tagging support is not available or enabled. * 126 (Invalid Comment Tag) + The comment tag provided was not valid (e.g. contains invalid characters). * 127 (Comment Tag Too Short) + The comment tag provided is shorter than the minimum length. * 128 (Comment Tag Too Long) + The comment tag provided is longer than the maximum length. content: application/json: schema: @@ -1047,8 +1068,8 @@ paths: required: - text example: - text: This issue has been fixed in bug 1234. id: 2345 + text: This issue has been fixed in bug 1234. responses: "200": description: Text containing the HTML rendering @@ -1063,7 +1084,7 @@ paths: html: This issue has been fixed in bug 1234. default: description: | - Various error responses, including those thrown by :ref:`rest_single_bug`. + Various error responses, including those thrown by [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). content: application/json: schema: @@ -1782,17 +1803,13 @@ components: time: description: The time (in Bugzilla’s timezone) that the comment was added. type: string + deprecated: true format: date-time creation_time: description: | - This is exactly same as the ``time`` key. Use this - field instead of ``time`` for consistency with other - methods including :ref:`rest_single_bug` and - :ref:`rest_attachments`. + This is exactly same as the ``time`` key. Use this field instead of ``time`` for consistency with other methods including [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) and :ref:`rest_attachments`. - For compatibility, ``time`` is still usable. However, - please note that ``time`` may be deprecated and removed - in a future release. + For compatibility, ``time`` is still usable. However, please note that ``time`` may be deprecated and removed in a future release. type: string format: date-time is_private: From 74085863a9ec37abd1690e79ab993f56cbe85e77 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 13:57:33 +0100 Subject: [PATCH 18/29] Aligned "Bugs" section [skip ci] --- openapi.yaml | 451 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 337 insertions(+), 114 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 51f6c17eb6..653257a364 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -18,6 +18,16 @@ paths: description: Gets information about a particular bug using its ID or alias. parameters: - $ref: "#/components/parameters/BugIdOrAlias" + - name: include_fields + in: query + description: | + Specify the fields to be included in the return value. + + Custom fields are included by default, similar to normal bug fields. To include only custom fields, use `_custom` in include_fields. Extra fields can be retrieved by specifying `_extra` or the field name in include_fields. + schema: + type: array + items: + type: string responses: "200": description: A list of Bugs @@ -169,12 +179,8 @@ paths: last_change_time: "2014-09-29T14:25:35Z" default: description: | - Various error responses, including: + This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: - * 100 (Invalid Bug ID) - The bug_id you specified doesn't exist in the database. - * 102 (Access Denied) - You do not have access to the bug_id you specified. * 129 (Flag Status Invalid) The flag status is invalid. * 130 (Flag Modification Denied) @@ -249,7 +255,7 @@ paths: removed: "" default: description: | - Same as Get Bug. + Same as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). content: application/json: schema: @@ -266,22 +272,38 @@ paths: in: query description: The unique alias of this bug. A null value will be returned if this bug has no alias. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: assigned_to in: query description: The login name of a user that a bug is assigned to. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: component in: query - description: The name of the Component that the bug is in. + description: "The name of the Component that the bug is in. Note that if there are multiple Components with the same name, and you search for that name, bugs in *all* those Components will be returned. If you don't want this, be sure to also specify the ``product`` argument." schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: count_only in: query description: 'If set to true, an object with a single key called "bug_count" will be returned, which is the number of bugs that matched the search.' schema: - type: boolean + oneOf: + - type: boolean + - type: array + items: + type: boolean - name: creation_time in: query description: Searches for bugs that were created at this time or later. May not be an array. @@ -292,22 +314,48 @@ paths: in: query description: The login name of the user who created the bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string + - name: reporter + in: query + description: "The name of the user who reported the bug, for backwards compatibility with older Bugzillas." + schema: + oneOf: + - type: string + - type: array + items: + type: string + deprecated: true - name: description in: query description: The description (initial comment) of the bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: filed_via in: query description: Searches for bugs that were created with this method. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: id in: query description: The numeric ID of the bug. schema: - type: integer + oneOf: + - type: integer + - type: array + items: + type: integer - name: last_change_time in: query description: Searches for bugs that were modified at this time or later. May not be an array. @@ -316,104 +364,172 @@ paths: format: date-time - name: limit in: query - description: Limit the number of results returned. + description: "Limit the number of results returned. If the value is unset, zero or greater than the maximum value set by the administrator, which is 10,000 by default, then the maximum value will be used instead. This is a preventive measure against DoS-like attacks on Bugzilla. Use the ``offset`` argument described below to retrieve more results." schema: type: integer - name: longdescs.count in: query - description: The number of comments a bug has. + description: "The number of comments a bug has. The bug's description is the first comment. For example, to find bugs which someone has commented on after they have been filed, search on ``longdescs.count`` *greater than* 1." schema: type: integer - name: offset in: query - description: "Used in conjunction with the limit argument, offset defines the starting position for the search." + description: "Used in conjunction with the ``limit`` argument, ``offset`` defines the starting position for the search. For example, given a search that would return 100 bugs, setting ``limit`` to 10 and ``offset`` to 10 would return bugs 11 through 20 from the set of 100." schema: type: integer - name: op_sys in: query description: The "Operating System" field of a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: platform in: query description: The Platform (sometimes called "Hardware") field of a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: priority in: query description: The Priority field on a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: product in: query description: The name of the Product that the bug is in. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: quicksearch in: query description: Search for bugs using quicksearch syntax. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: resolution in: query - description: The current resolution--only set if a bug is closed. + description: The current resolution--only set if a bug is closed. You can find open bugs by searching for bugs with an empty resolution. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: severity in: query description: The Severity field on a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: status in: query description: "The current status of a bug (not including its resolution, if it has one, which is a separate field above)." schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: summary in: query - description: Searches for substrings in the single-line Summary field on bugs. + description: 'Searches for substrings in the single-line Summary field on bugs. If you specify an array, then bugs whose summaries match *any* of the passed substrings will be returned. Note that unlike searching in the Bugzilla UI, substrings are not split on spaces. So searching for ``foo bar`` will match "This is a foo bar" but not "This foo is a bar". ``[''foo'', ''bar'']``, would, however, match the second item.' schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: tags in: query - description: Searches for a bug with the specified tag. + description: "Searches for a bug with the specified tag. If you specify an array, then any bugs that match *any* of the tags will be returned. Note that tags are personal to the currently logged in user." schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: target_milestone in: query - description: The Target Milestone field of a bug. + description: 'The Target Milestone field of a bug. Note that even if this Bugzilla does not have the Target Milestone field enabled, you can still search for bugs by Target Milestone. However, it is likely that in tha case, most bugs will not have a Target Milestone set (it defaults to "---" when the field isn''t enabled).' schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: qa_contact in: query - description: The login name of the bug's QA Contact. + description: "he login name of the bug's QA Contact. Note that even if this Bugzilla does not have the QA Contact field enabled, you can still search for bugs by QA Contact (though it is likely that no bug will have a QA Contact set, if the field is disabled)." schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: triage_owner in: query description: The login name of the Triage Owner of a bug's component. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: type in: query description: The Type field on a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: url in: query description: The "URL" field of a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: version in: query description: The Version field of a bug. schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string - name: whiteboard in: query - description: Search the "Status Whiteboard" field on bugs for a substring. + description: 'Search the "Status Whiteboard" field on bugs for a substring. Works the same as the ``summary`` field described above, but searches the Status Whiteboard field.' schema: - type: string + oneOf: + - type: string + - type: array + items: + type: string responses: "200": description: A list of bugs matching the search criteria @@ -458,7 +574,8 @@ paths: description: | If you specify an invalid value for a particular field, you just won’t get any results for that value. - * 1000 (Parameters Required) You may not search without any search terms. + * 1000 (Parameters Required) + You may not search without any search terms. content: application/json: schema: @@ -468,16 +585,11 @@ paths: post: summary: Create a new bug description: | - This endpoint allows you to create a new bug in Bugzilla. If you specify any - invalid fields, an error will be thrown stating which field is invalid. - If you specify any fields you are not allowed to set, they will just be - set to their defaults or ignored. + This endpoint allows you to create a new bug in Bugzilla. If you specify any invalid fields, an error will be thrown stating which field is invalid. If you specify any fields you are not allowed to set, they will just be set to their defaults or ignored. You cannot currently set all the items here that you can set on enter_bug.cgi. - The WebService interface may allow you to set things other than those listed - here, but realize that anything undocumented here may likely change in the - future. + The WebService interface may allow you to set things other than those listed here, but realize that anything undocumented here may likely change in the future. requestBody: content: application/json: @@ -540,7 +652,10 @@ paths: You didn't specify a type for the bug. * 504 (Invalid User) Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details. - deprecated: false + content: + application/json: + schema: + $ref: "#/components/schemas/Error" tags: - Bugs "/bug/{bug_id}/graph": @@ -575,7 +690,7 @@ paths: default: false - name: relationship in: query - description: 'One of "dependencies", "duplicates", or "regressions".' + description: "The default is the dependencies graph. To return the graph for other types, pass this parameter." schema: type: string default: dependencies @@ -588,24 +703,27 @@ paths: description: | A graph of bug relationships - The default return object will be an object with two trees based on the type of relationship selected. For dependencies, it will be blocked and dependson. For regressions, it will be be regresses and regressed_by. And for duplicates, it will be dupe_of and dupe. + The default return object will be an object with two trees based on the type of relationship selected. For dependencies, it will be ``blocked`` and ``dependson`` For regressions, it will be be ``regresses`` and ``regressed_by``. And for duplicates, it will be ``dupe_of`` and ``dupe``. content: application/json: schema: oneOf: - type: object + title: dependencies properties: blocked: $ref: "#/components/schemas/BugNode" dependson: $ref: "#/components/schemas/BugNode" - type: object + title: regressions properties: regresses: $ref: "#/components/schemas/BugNode" regressed_by: $ref: "#/components/schemas/BugNode" - type: object + title: duplicates properties: dupe_of: $ref: "#/components/schemas/BugNode" @@ -696,9 +814,7 @@ paths: - name: limit in: query description: | - Limit the number of results returned. If the value is unset, zero, or greater than - the maximum value set by the administrator (default: 10,000), the maximum value - will be used instead. + Limit the number of results returned. If the value is unset, zero, or greater than the maximum value set by the administrator (default: 10,000), the maximum value will be used instead. This is a preventive measure against DoS-like attacks on Bugzilla. schema: type: integer responses: @@ -735,6 +851,10 @@ paths: removed: "" default: description: Various error responses + content: + application/json: + schema: + $ref: "#/components/schemas/Error" tags: - Bugs "/bug/{id_or_alias}/comment": @@ -853,7 +973,6 @@ paths: You specified an id in the "comment_ids" argument that is invalid--either you specified something that wasn't a number, or there is no comment with that id. - content: application/json: schema: @@ -1107,11 +1226,13 @@ components: type: object properties: actual_time: - description: The total number of hours that this bug has taken so far. + description: "The total number of hours that this bug has taken so far. If you are not in the time-tracking group, this field will not be included in the return value." type: number alias: - description: The unique alias of this bug. A null value will be returned if this bug has no alias. - type: string + description: The unique alias of this bug. A `null` value will be returned if this bug has no alias. + type: + - string + - null assigned_to: description: The login name of the user to whom the bug is assigned. type: string @@ -1148,8 +1269,9 @@ components: creator_detail: $ref: "#/components/schemas/User" deadline: - description: "The day that this bug is due to be completed, in the format YYYY-MM-DD." + description: "The day that this bug is due to be completed, in the format `YYYY-MM-DD`." type: string + format: date depends_on: description: The IDs of bugs that this bug "depends on". type: array @@ -1157,14 +1279,16 @@ components: type: integer dupe_of: description: "The bug ID of the bug that this bug is a duplicate of. If this bug isn't a duplicate of any bug, this will be null." - type: integer + type: + - integer + - null duplicates: description: The ids of bugs that are marked as duplicate of this bug. type: array items: type: integer estimated_time: - description: The number of hours that it was estimated that this bug would take. + description: "The number of hours that it was estimated that this bug would take. If you are not in the time-tracking group, this field will not be included in the return value." type: number flags: description: An array of objects containing the information about flags currently set for the bug. @@ -1183,10 +1307,13 @@ components: description: "If true, this bug can be accessed by members of the CC list, even if they are not in the groups the bug is restricted to." type: boolean is_confirmed: - description: true if the bug has been confirmed. Usually this means that the bug has at some point been moved out of the UNCONFIRMED status and into another open status. + description: "``true`` if the bug has been confirmed. Usually this means that the bug has at some point been moved out of the ``UNCONFIRMED`` status and into another open status." + type: boolean + is_open: + description: "`true` if this bug is open, ``false`` if it is closed." type: boolean is_creator_accessible: - description: "If true, this bug can be accessed by the creator of the bug, even if they are not a member of the groups the bug is restricted to." + description: "If `true`, this bug can be accessed by the creator of the bug, even if they are not a member of the groups the bug is restricted to." type: boolean keywords: description: Each keyword that is on this bug. @@ -1197,6 +1324,9 @@ components: description: When the bug was last changed. type: string format: date-time + comment_count: + description: Number of comments associated with the bug. + type: integer op_sys: description: The name of the operating system that the bug was filed against. type: string @@ -1213,6 +1343,7 @@ components: description: The login name of the current QA Contact on the bug. type: string qa_contact_detail: + description: An object containing detailed user information for the qa_contact. $ref: "#/components/schemas/User" regressed_by: description: The IDs of bugs that introduced this bug. @@ -1225,7 +1356,7 @@ components: items: type: integer remaining_time: - description: The number of hours of work remaining until work on this bug is complete. + description: "The number of hours of work remaining until work on this bug is complete. If you are not in the time-tracking group, this field will not be included in the return value." type: number resolution: description: "The current resolution of the bug, or an empty string if the bug is open." @@ -1251,7 +1382,7 @@ components: description: The type of the bug. type: string update_token: - description: The token that you would have to pass to the process_bug.cgi page in order to update this bug. This changes every time the bug is updated. This field is not returned to logged-out users. + description: The token that you would have to pass to the ``process_bug.cgi`` page in order to update this bug. This changes every time the bug is updated. This field is not returned to logged-out users. type: string url: description: "A URL that demonstrates the problem described in the bug, or is somehow related to the bug report." @@ -1262,6 +1393,118 @@ components: whiteboard: description: The value of the "status whiteboard" field on the bug. type: string + attachments: + description: | + Each array item is an Attachment object. See :ref:`rest_attachments` for details of the object. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + $ref: "#/components/schemas/Attachment" + comments: + description: | + Each array item is a Comment object. See :ref:`rest_comments` for details of the object. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + $ref: "#/components/schemas/Comment" + counts: + description: | + An object containing the counts of various items. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: object + properties: + attachments: + description: The number of attachments. + type: integer + cc: + description: The number of carbon copies (CC). + type: integer + comments: + description: The number of comments. + type: integer + keywords: + description: The number of keywords. + type: integer + blocks: + description: The number of blocks. + type: integer + depends_on: + description: The number of dependencies. + type: integer + regressed_by: + description: The number of items causing regression. + type: integer + regressions: + description: The number of regressions. + type: integer + duplicates: + description: The number of duplicate items. + type: integer + description: + description: | + The description (initial comment) of the bug. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + filed_via: + description: | + How the bug was filed, e.g. `standard_form`. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + history: + description: | + Each array item is a History object. See :ref:`rest_history` for details of the object. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + $ref: "#/components/schemas/History" + tags: + description: | + Each array item is a tag name. Note that tags are personal to the currently logged in user and are not the same as comment tags. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + type: string + triage_owner: + description: | + The login name of the Triage Owner of the bug's component. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + triage_owner_detail: + description: | + An object containing detailed user information for the `triage_owner`. To see the keys included in the user detail object, see below. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: object + last_change_time_non_bot: + description: | + When the bug was last changed human and not a bot. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + format: date-time + additionalProperties: + description: | + Every custom field in this installation will also be included in the return value. Most fields are returned as strings. However, some field types have different return values. + + Normally custom fields are returned by default similar to normal bug fields or you can specify only custom fields by using ``_custom`` in ``include_fields``. Flag: type: object properties: @@ -1316,14 +1559,16 @@ components: description: The numeric ID of the bug. type: integer alias: - description: The unique alias of this bug. A null value will be returned if this bug has no alias. - type: string + description: The unique alias of this bug. A `null` value will be returned if this bug has no alias. + type: + - string + - null history: description: An array of History objects. type: array items: - $ref: "#/components/schemas/History" - History: + $ref: "#/components/schemas/BugHistory" + BugHistory: type: object properties: when: @@ -1334,11 +1579,11 @@ components: description: The login name of the user who performed the bug change. type: string changes: - description: An array of Change objects. + description: An array of Change objects which contain all the changes that happened to the bug at this time (as specified by ``when``). type: array items: - $ref: "#/components/schemas/Change" - Change: + $ref: "#/components/schemas/BugChange" + BugChange: type: object properties: field_name: @@ -1353,7 +1598,6 @@ components: attachment_id: description: "The ID of the attachment that was changed. This only appears if the change was to an attachment, otherwise `attachment_id` will not be present in this object." type: integer - nullable: true NewBug: type: object properties: @@ -1445,6 +1689,8 @@ components: type: array items: type: integer + additionalProperties: + description: "In addition to the above parameters, if your installation has any custom fields, you can set them just by passing in the name of the field and its value as a string." required: - product - component @@ -1513,7 +1759,7 @@ components: items: type: string is_cc_accessible: - description: Whether or not users in the CC list are allowed to access the bug. + description: "Whether or not users in the CC list are allowed to access the bug, even if they aren't in a group that can normally access the bug." type: boolean comment: description: A comment on the change. @@ -1523,16 +1769,14 @@ components: description: The actual text of the comment. type: string comment: - description: An alias for the comment body. (For compatibility with the parameters to rest_add_comment) + description: "An alias for the comment body. (For compatibility with the parameters to :ref:`rest_add_comment`)" type: string is_private: description: "Whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown." type: boolean comment_is_private: description: | - This is how you update the privacy of comments that are already on a bug. - - This is a object, where the keys are the ID of comments. + This is how you update the privacy of comments that are already on a bug. This is a object, where the keys are the ``int`` ID of comments (not their count on a bug, like #1, #2, #3, but their globally-unique ID, as returned by :ref:`rest_comments` and the value is a ``boolean`` which specifies whether that comment should become private (``true``) or public (``false``). The comment IDs must be valid for the bug being updated. Thus, it is not practical to use this while updating multiple bugs at once, as a single comment ID will never be valid on multiple bugs. type: object @@ -1543,17 +1787,14 @@ components: description: The Component the bug is in. type: string deadline: - description: The Deadline field is a date specifying when the bug must be completed by. + description: "The Deadline field is a date specifying when the bug must be completed by, in the format ``YYYY-MM-DD``." type: string format: date dupe_of: - description: | - The bug that this bug is a duplicate of. - - If you want to mark a bug as a duplicate, the safest thing to do is to set this value and not set the status or resolution fields. They will automatically be set by Bugzilla to the appropriate values for duplicate bugs. + description: "The bug that this bug is a duplicate of. If you want to mark a bug as a duplicate, the safest thing to do is to set this value and *not* set the ``status`` or ``resolution`` fields. They will automatically be set by Bugzilla to the appropriate values for duplicate bugs." type: integer estimated_time: - description: "The total estimate of time required to fix the bug, in hours." + description: "The total estimate of time required to fix the bug, in hours. This is the *total* estimate, not the amount of time remaining to fix it." type: number flags: description: | @@ -1562,7 +1803,7 @@ components: Of any item, at least the status and one of type_id, id, or name must be specified. If a type_id or name matches a single currently set flag, the flag will be updated unless new is specified. type: array items: - $ref: "#/components/schemas/FlagChange" + $ref: "#/components/schemas/FlagUpdate" groups: description: The groups a bug is in. type: object @@ -1608,29 +1849,14 @@ components: type: string product: description: | - The name of the product that the bug is in. If - you change this, you will probably also want to - change ``target_milestone``, ``version``, and - ``component``, since those have different legal - values in every product. + The name of the product that the bug is in. If you change this, you will probably also want to change ``target_milestone``, ``version``, and ``component``, since those have different legal values in every product. - If you cannot change the ``target_milestone`` - field, it will be reset to the default for the - product, when you move a bug to a new product. + If you cannot change the ``target_milestone`` field, it will be reset to the default for the product, when you move a bug to a new product. - You may also wish to add or remove groups, as - which groups are - valid on a bug depends on the product. Groups - that are not valid in the new product will be - automatically removed, and groups which are - mandatory in the new product will be - automatically added, but no other automatic group - changes will be done. + You may also wish to add or remove groups, as which groups are valid on a bug depends on the product. Groups that are not valid in the new product will be automatically removed, and groups which are mandatory in the new product will be automatically added, but no other automatic group changes will be done. > **Note:** - Users can only move a bug into a product if - they would normally have permission to file - new bugs in that product. + Users can only move a bug into a product if they would normally have permission to file new bugs in that product. type: string qa_contact: description: The full login name of the bug's QA Contact. @@ -1639,18 +1865,13 @@ components: description: Whether or not the bug's reporter is allowed to access the bug. type: boolean remaining_time: - description: | - How much work time is remaining to fix the bug, - in hours. If you set ``work_time`` but don't - explicitly set ``remaining_time``, then the - ``work_time`` will be deducted from the bug's - ``remaining_time``. + description: "How much work time is remaining to fix the bug, in hours. If you set ``work_time`` but don't explicitly set ``remaining_time``, then the ``work_time`` will be deducted from the bug's ``remaining_time``." type: number reset_assigned_to: description: "If true, the `assigned_to` field will be reset to the default for the component that the bug is in. (If you have set the component at the same time as using this, then the component used will be the new component, not the old one.)" type: boolean reset_qa_contact: - description: "If true, the `qa_contact` field will be reset to the default for the component that the bug is in." + description: "If true, the ``qa_contact`` field will be reset to the default for the component that the bug is in. (If you have set the component at the same time as using this, then the component used will be the new component, not the old one.)" type: boolean resolution: description: |- @@ -1698,6 +1919,8 @@ components: work_time: description: "The number of hours worked on this bug as part of this change. If you set ``work_time`` but don't explicitly set ``remaining_time``, then the ``work_time`` will be deducted from the bug's ``remaining_time``." type: number + additionalProperties: + description: "In addition to the above parameters, if your installation has any custom fields, you can set them just by passing in the name of the field and its value as a string." required: - ids BugRelationship: @@ -1718,7 +1941,7 @@ components: type: array items: type: integer - FlagChange: + FlagUpdate: type: object properties: name: @@ -1803,8 +2026,8 @@ components: time: description: The time (in Bugzilla’s timezone) that the comment was added. type: string - deprecated: true format: date-time + deprecated: true creation_time: description: | This is exactly same as the ``time`` key. Use this field instead of ``time`` for consistency with other methods including [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) and :ref:`rest_attachments`. From d4ccf99319d31c0c1bd1210b28e96d5c64819563 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 14:21:39 +0100 Subject: [PATCH 19/29] Added "Get Attachment" --- openapi.yaml | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 653257a364..8ff2bfd200 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -12,6 +12,94 @@ servers: - url: "https://bugzilla-dev.allizom.org/rest" description: Test instance for Bugzilla. paths: + "/bug/{bug_id}/attachment": + get: + summary: Get all attachments for a bug + description: This allows you to get all current attachments for a bug. + parameters: + - name: bug_id + in: path + description: Integer bug ID. + required: true + schema: + type: integer + responses: + "200": + description: A list of Attachments + content: + application/json: + schema: + type: object + properties: + bugs: + description: | + This is an object that has integer bug IDs for keys and the values are arrays of objects as attachments. + type: object + additionalProperties: + type: array + items: + $ref: "#/components/schemas/Attachment" + attachments: + type: object + const: {} + example: + bugs: + "1345": + - (attachment) + - (attachment) + attachments: {} + default: + description: This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + tags: + - Attachments + "/bug/attachment/{attachment_id}": + get: + summary: Get a specific attachment + description: This allows you to get a specific attachment based on the attachment ID. + parameters: + - name: attachment_id + in: path + description: Integer attachment ID. + required: true + schema: + type: integer + responses: + "200": + description: A single Attachment + content: + application/json: + schema: + type: object + properties: + bugs: + type: object + const: {} + attachments: + description: | + This is an object where the attachment ids point directly to objects describing the individual attachment. + type: object + additionalProperties: + $ref: "#/components/schemas/Attachment" + example: + bugs: {} + attachments: + "234": (attachment) + default: + description: | + This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{bug_id}/get). In addition, it can also throw the following error: + + * 304 (Auth Failure, Attachment is Private) + You specified the id of a private attachment in the "attachment_ids" argument, and you are not in the "insider group" that can see private attachments. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + tags: + - Attachments "/bug/{id_or_alias}": get: summary: Get information about a bug @@ -1222,6 +1310,60 @@ components: - string - integer schemas: + Attachment: + type: object + properties: + data: + description: The raw data of the attachment, encoded as Base64. + type: string + format: base64 + size: + description: The length (in bytes) of the attachment. + type: integer + creation_time: + description: The time the attachment was created. + type: string + format: date-time + last_change_time: + description: The last time the attachment was modified. + type: string + format: date-time + id: + description: The numeric ID of the attachment. + type: integer + bug_id: + description: The numeric ID of the bug that the attachment is attached to. + type: integer + file_name: + description: The file name of the attachment. + type: string + summary: + description: A short string describing the attachment. + type: string + content_type: + description: The MIME type of the attachment. + type: string + is_private: + description: '``true`` if the attachment is private (only visible to a certain group called the "insidergroup"), ``false`` otherwise.' + type: boolean + is_obsolete: + description: "``true`` if the attachment is obsolete, ``false`` otherwise." + type: boolean + is_patch: + description: "``true`` if the attachment is a patch, ``false`` otherwise." + type: boolean + creator: + description: The login name of the user that created the attachment. + type: string + creator_detail: + description: An object containing detailed user information for the creator. + $ref: "#/components/schemas/User" + flags: + description: Array of objects, each containing the information about the flag currently set for each attachment. + type: array + items: + $ref: "#/components/schemas/Flag" + Bug: type: object properties: From 89ae6b5a46999924860f9936152c465610a6e0c6 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 14:35:24 +0100 Subject: [PATCH 20/29] Added "Create Attachment" --- openapi.yaml | 130 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 126 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 8ff2bfd200..afc0fe9b4c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -49,7 +49,130 @@ paths: - (attachment) attachments: {} default: - description: This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). + description: "This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get)." + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + tags: + - Attachments + post: + summary: Create attachment on a bug + description: This allows you to add an attachment to a bug in Bugzilla. + parameters: + - $ref: "#/components/parameters/BugId" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: The IDs or aliases of bugs that you want to add this attachment to. The same attachment and comment will be added to all these bugs. + type: array + items: + type: + - string + - integer + data: + description: "The content of the attachment. You must encode it in base64 using an appropriate client library such as ``MIME::Base64`` for Perl." + type: string + format: base64 + file_name: + description: The "file name" that will be displayed in the UI for this attachment and also downloaded copies will be given. + type: string + summary: + description: A short string describing the attachment. + type: string + content_type: + description: "The MIME type of the attachment, like ``text/plain`` or ``image/png``." + type: string + comment: + description: A comment to add along with this attachment. + type: string + is_patch: + description: "``true`` if Bugzilla should treat this attachment as a patch. If you specify this, you do not need to specify a ``content_type``. The ``content_type`` of the attachment will be forced to ``text/plain``. Defaults to ``false`` if not specified." + type: boolean + is_private: + description: '``true`` if the attachment should be private (restricted to the "insidergroup"), ``false`` if the attachment should be public. Defaults to ``false`` if not specified.' + type: boolean + flags: + description: Flags objects to add to the attachment. + type: array + items: + $ref: "#/components/schemas/NewFlag" + bug_flags: + description: Flag objects to add to the attachment's bug. + type: array + items: + $ref: "#/components/schemas/NewFlag" + required: + - ids + - data + - file_name + - summary + - content_type + example: + ids: + - 35 + is_patch: true + comment: This is a new attachment comment + summary: Test Attachment + content_type: text/plain + data: (Some base64 encoded content) + file_name: test_attachment.patch + obsoletes: [] + is_private: false + flags: + - name: review + status: "?" + requestee: user@bugzilla.org + new: true + responses: + "200": + description: Attachment IDs created. + content: + application/json: + schema: + type: object + properties: + ids: + type: array + items: + type: string + example: + ids: + - "2797" + default: + description: | + This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: + + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required + permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify + the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag of the comment to true but the Markdown feature is not enabled. + * 600 (Attachment Too Large) + You tried to attach a file that was larger than Bugzilla will accept. + * 601 (Invalid MIME Type) + You specified a "content_type" argument that was blank, not a valid + MIME type, or not a MIME type that Bugzilla accepts for attachments. + * 603 (File Name Not Specified) + You did not specify a valid for the "file_name" argument. + * 604 (Summary Required) + You did not specify a value for the "summary" argument. + * 606 (Empty Data) + You set the "data" field to an empty string. content: application/json: schema: @@ -1314,7 +1437,7 @@ components: type: object properties: data: - description: The raw data of the attachment, encoded as Base64. + description: "The raw data of the attachment, encoded as Base64." type: string format: base64 size: @@ -1359,11 +1482,10 @@ components: description: An object containing detailed user information for the creator. $ref: "#/components/schemas/User" flags: - description: Array of objects, each containing the information about the flag currently set for each attachment. + description: "Array of objects, each containing the information about the flag currently set for each attachment." type: array items: $ref: "#/components/schemas/Flag" - Bug: type: object properties: From 95c9186dcaf7f2bf1a590046026716dad4e8523f Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 14:48:34 +0100 Subject: [PATCH 21/29] Added "Update Attachment" [skip ci] --- openapi.yaml | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index afc0fe9b4c..d99dbce431 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -223,6 +223,149 @@ paths: $ref: "#/components/schemas/Error" tags: - Attachments + put: + summary: Update attachment metadata + description: This allows you to update attachment metadata in Bugzilla. + parameters: + - name: attachment_id + in: path + description: Integer attachment ID. + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: The IDs of the attachments you want to update. + type: array + items: + type: string + file_name: + description: The "file name" that will be displayed in the UI for this attachment. + type: string + summary: + description: A short string describing the attachment. + type: string + comment: + description: An optional comment to add to the attachment's bug. + type: string + content_type: + description: "The MIME type of the attachment, like ``text/plain`` or ``image/png``." + type: string + is_patch: + description: "``true`` if Bugzilla should treat this attachment as a patch. If you specify this, you do not need to specify a ``content_type``. The ``content_type`` of the attachment will be forced to ``text/plain``." + type: boolean + is_private: + description: "`true` if the attachment should be private, `false` if the attachment should be public." + type: boolean + is_obsolete: + description: "`true` if the attachment is obsolete, `false` otherwise." + type: boolean + flags: + description: An array of Flag objects with changes to the flags. + type: array + items: + $ref: "#/components/schemas/FlagUpdate" + bug_flags: + description: An optional array of Flag objects with changes to the flags of the attachment's bug. + type: array + items: + $ref: "#/components/schemas/FlagUpdate" + required: + - ids + example: + ids: + - 2796 + summary: Test XML file + comment: Changed this from a patch to a XML file + content_type: text/xml + is_patch: 0 + responses: + "200": + description: Attachment metadata updated. + content: + application/json: + schema: + type: object + properties: + attachments: + type: array + items: + type: object + properties: + id: + description: The ID of the attachment that was updated. + type: integer + last_change_time: + description: "The exact time that this update was done at, for this attachment. If no update was done (that is, no fields had their values changed and no comment was added) then this will instead be the last time the attachment was updated." + type: string + format: date-time + changes: + description: "The changes that were actually done on this attachment. The keys are the names of the fields that were changed, and the values are an object with two items:" + type: object + additionalProperties: + type: object + properties: + added: + description: The values that were added to this field. Possibly a comma-and-space-separated list if multiple values were added. + type: string + removed: + description: The values that were removed from this field. + type: string + example: + attachments: + - id: 2796 + last_change_time: "2014-09-29T14:41:53Z" + changes: + content_type: + added: text/xml + removed: text/plain + is_patch: + added: "0" + removed: "1" + summary: + added: Test XML file + removed: test patch + default: + description: | + This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: + + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required + permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 132 (Flag not Unique) + The flag specified has been set multiple times. You must specify the id + value to update the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify + the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag of the "comment" to true but Markdown feature is + not enabled. + * 601 (Invalid MIME Type) + You specified a "content_type" argument that was blank, not a valid + MIME type, or not a MIME type that Bugzilla accepts for attachments. + * 603 (File Name Not Specified) + You did not specify a valid for the "file_name" argument. + * 604 (Summary Required) + You did not specify a value for the "summary" argument. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + tags: + - Attachments "/bug/{id_or_alias}": get: summary: Get information about a bug From 196a993a407f2bf751e93f6e1802ac965fcc40e1 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 15:50:56 +0100 Subject: [PATCH 22/29] Resolved refrences --- openapi.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index d99dbce431..35ca973bb9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1802,7 +1802,7 @@ components: type: string attachments: description: | - Each array item is an Attachment object. See :ref:`rest_attachments` for details of the object. + Each array item is an Attachment object. See [Get Attachment](#tag/Attachments/paths/~1bug~1attachment~1{attachment_id}/get) for details of the object. > **Note:** This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. @@ -1811,7 +1811,7 @@ components: $ref: "#/components/schemas/Attachment" comments: description: | - Each array item is a Comment object. See :ref:`rest_comments` for details of the object. + Each array item is a Comment object. See [Get Comment](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) for details of the object. > **Note:** This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. @@ -1869,7 +1869,7 @@ components: type: string history: description: | - Each array item is a History object. See :ref:`rest_history` for details of the object. + Each array item is a History object. See [Get History](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) for details of the object. > **Note:** This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. @@ -2067,7 +2067,7 @@ components: description: The status that this bug should start out as. Note that only certain statuses can be set on bug creation. type: string resolution: - description: "If you are filing a closed bug, then you will have to specify a resolution. You cannot currently specify a resolution of ``DUPLICATE`` for new bugs, though. That must be done with :ref:`rest_update_bug`." + description: "If you are filing a closed bug, then you will have to specify a resolution. You cannot currently specify a resolution of ``DUPLICATE`` for new bugs, though. That must be done with [Get History](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get)." type: string target_milestone: description: A valid target milestone for this product. @@ -2176,14 +2176,14 @@ components: description: The actual text of the comment. type: string comment: - description: "An alias for the comment body. (For compatibility with the parameters to :ref:`rest_add_comment`)" + description: "An alias for the comment body. (For compatibility with the parameters to [Create Comments](#tag/Comments/paths/~1bug~1{id}~1comment/post))" type: string is_private: description: "Whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown." type: boolean comment_is_private: description: | - This is how you update the privacy of comments that are already on a bug. This is a object, where the keys are the ``int`` ID of comments (not their count on a bug, like #1, #2, #3, but their globally-unique ID, as returned by :ref:`rest_comments` and the value is a ``boolean`` which specifies whether that comment should become private (``true``) or public (``false``). + This is how you update the privacy of comments that are already on a bug. This is a object, where the keys are the ``int`` ID of comments (not their count on a bug, like #1, #2, #3, but their globally-unique ID, as returned by [Get Comment](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) and the value is a ``boolean`` which specifies whether that comment should become private (``true``) or public (``false``). The comment IDs must be valid for the bug being updated. Thus, it is not practical to use this while updating multiple bugs at once, as a single comment ID will never be valid on multiple bugs. type: object @@ -2437,7 +2437,7 @@ components: deprecated: true creation_time: description: | - This is exactly same as the ``time`` key. Use this field instead of ``time`` for consistency with other methods including [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) and :ref:`rest_attachments`. + This is exactly same as the ``time`` key. Use this field instead of ``time`` for consistency with other methods including [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) and [Get Attachment](#tag/Attachments/paths/~1bug~1attachment~1{attachment_id}/get). For compatibility, ``time`` is still usable. However, please note that ``time`` may be deprecated and removed in a future release. type: string From 4c00e807b913d7122333fe387cb750b5449bd944 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 17:06:01 +0100 Subject: [PATCH 23/29] Added security schemes --- openapi.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 35ca973bb9..86d2da09f9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2458,6 +2458,33 @@ components: type: string code: type: integer + securitySchemes: + X-BUGZILLA-API-KEY: + type: apiKey + description: | + You can specify 'X-BUGZILLA-API-KEY' header with the API key as a value to any request, and you will be authenticated as that user if the key is correct and has not been revoked. + + You can set up an API key by using the [API Keys tab](https://bmo.readthedocs.io/en/latest/using/preferences.html#api-keys) in the Preferences pages. + in: header + name: X-BUGZILLA-API-KEY + Bugzilla_api_key: + type: apiKey + description: | + You can specify an API key via the `Bugzilla_api_key` query parameter, and you will be authenticated as that user if the key is correct and has not been revoked. + + > [!WARNING] + It should be noted that this authentication method is not recommended for use and it is likely to be deprecated in future versions of BMO, due to security concerns. + in: query + name: Bugzilla_api_key + api_key: + type: apiKey + description: | + You can specify an API key via the `api_key` query parameter, and you will be authenticated as that user if the key is correct and has not been revoked. + + > [!WARNING] + It should be noted that this authentication method is not recommended for use and it is likely to be deprecated in future versions of BMO, due to security concerns. + in: query + name: api_key tags: - name: Attachments description: "The Bugzilla API for creating, changing, and getting the details of attachments." From 11ad954a82f129829b61725c0267a715f29441fe Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 17:12:17 +0100 Subject: [PATCH 24/29] Improved description --- openapi.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 86d2da09f9..9b394f1adb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,7 +1,8 @@ openapi: 3.1.0 info: title: WebService API Reference - description: BMO is Mozilla's highly customized version of Bugzilla. + description: | + This is the standard REST API for external programs that want to interact with Bugzilla. It provides a REST interface to various Bugzilla functions. license: name: MPL-2.0 url: "https://github.com/mozilla-bteam/bmo/blob/master/LICENSE" From 3ac3c2ec2b9d69ace69ecf4f67b7b880aaa167ec Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Mon, 4 Dec 2023 17:16:49 +0100 Subject: [PATCH 25/29] Split OpenAPI spec into individual files --- openapi.yaml | 2577 ----------------- .../components/parameters/BugIdOrAlias.yaml | 8 + openapi/components/schemas/Attachment.yaml | 56 + openapi/components/schemas/Bug.yaml | 331 +++ openapi/components/schemas/BugChange.yaml | 17 + openapi/components/schemas/BugHistory.yaml | 16 + openapi/components/schemas/BugNode.yaml | 6 + .../components/schemas/BugRelationship.yaml | 21 + openapi/components/schemas/BugUpdate.yaml | 296 ++ .../components/schemas/BugWithHistory.yaml | 17 + openapi/components/schemas/Comment.yaml | 58 + openapi/components/schemas/Error.yaml | 11 + openapi/components/schemas/FieldChange.yaml | 12 + openapi/components/schemas/Flag.yaml | 30 + openapi/components/schemas/FlagUpdate.yaml | 24 + openapi/components/schemas/NewBug.yaml | 129 + openapi/components/schemas/NewFlag.yaml | 16 + openapi/components/schemas/UpdatedBug.yaml | 16 + openapi/components/schemas/User.yaml | 19 + openapi/openapi.yaml | 219 ++ openapi/paths/bug.yaml | 458 +++ .../paths/bug_attachment_{attachment_id}.yaml | 215 ++ openapi/paths/bug_comment_render.yaml | 47 + openapi/paths/bug_comment_tags_{query}.yaml | 41 + openapi/paths/bug_comment_{comment_id}.yaml | 63 + .../paths/bug_comment_{comment_id}_tags.yaml | 67 + openapi/paths/bug_possible_duplicates.yaml | 70 + openapi/paths/bug_{bug_id}_attachment.yaml | 188 ++ openapi/paths/bug_{bug_id}_graph.yaml | 141 + openapi/paths/bug_{id_or_alias}.yaml | 202 ++ openapi/paths/bug_{id_or_alias}_comment.yaml | 67 + openapi/paths/bug_{id}_comment.yaml | 90 + openapi/paths/bug_{id}_history.yaml | 55 + 33 files changed, 3006 insertions(+), 2577 deletions(-) delete mode 100644 openapi.yaml create mode 100644 openapi/components/parameters/BugIdOrAlias.yaml create mode 100644 openapi/components/schemas/Attachment.yaml create mode 100644 openapi/components/schemas/Bug.yaml create mode 100644 openapi/components/schemas/BugChange.yaml create mode 100644 openapi/components/schemas/BugHistory.yaml create mode 100644 openapi/components/schemas/BugNode.yaml create mode 100644 openapi/components/schemas/BugRelationship.yaml create mode 100644 openapi/components/schemas/BugUpdate.yaml create mode 100644 openapi/components/schemas/BugWithHistory.yaml create mode 100644 openapi/components/schemas/Comment.yaml create mode 100644 openapi/components/schemas/Error.yaml create mode 100644 openapi/components/schemas/FieldChange.yaml create mode 100644 openapi/components/schemas/Flag.yaml create mode 100644 openapi/components/schemas/FlagUpdate.yaml create mode 100644 openapi/components/schemas/NewBug.yaml create mode 100644 openapi/components/schemas/NewFlag.yaml create mode 100644 openapi/components/schemas/UpdatedBug.yaml create mode 100644 openapi/components/schemas/User.yaml create mode 100644 openapi/openapi.yaml create mode 100644 openapi/paths/bug.yaml create mode 100644 openapi/paths/bug_attachment_{attachment_id}.yaml create mode 100644 openapi/paths/bug_comment_render.yaml create mode 100644 openapi/paths/bug_comment_tags_{query}.yaml create mode 100644 openapi/paths/bug_comment_{comment_id}.yaml create mode 100644 openapi/paths/bug_comment_{comment_id}_tags.yaml create mode 100644 openapi/paths/bug_possible_duplicates.yaml create mode 100644 openapi/paths/bug_{bug_id}_attachment.yaml create mode 100644 openapi/paths/bug_{bug_id}_graph.yaml create mode 100644 openapi/paths/bug_{id_or_alias}.yaml create mode 100644 openapi/paths/bug_{id_or_alias}_comment.yaml create mode 100644 openapi/paths/bug_{id}_comment.yaml create mode 100644 openapi/paths/bug_{id}_history.yaml diff --git a/openapi.yaml b/openapi.yaml deleted file mode 100644 index 9b394f1adb..0000000000 --- a/openapi.yaml +++ /dev/null @@ -1,2577 +0,0 @@ -openapi: 3.1.0 -info: - title: WebService API Reference - description: | - This is the standard REST API for external programs that want to interact with Bugzilla. It provides a REST interface to various Bugzilla functions. - license: - name: MPL-2.0 - url: "https://github.com/mozilla-bteam/bmo/blob/master/LICENSE" - version: 1.0.0 -servers: - - url: "https://bugzilla.mozilla.org/rest" - description: Production issue tracker for Firefox and other Mozilla products. - - url: "https://bugzilla-dev.allizom.org/rest" - description: Test instance for Bugzilla. -paths: - "/bug/{bug_id}/attachment": - get: - summary: Get all attachments for a bug - description: This allows you to get all current attachments for a bug. - parameters: - - name: bug_id - in: path - description: Integer bug ID. - required: true - schema: - type: integer - responses: - "200": - description: A list of Attachments - content: - application/json: - schema: - type: object - properties: - bugs: - description: | - This is an object that has integer bug IDs for keys and the values are arrays of objects as attachments. - type: object - additionalProperties: - type: array - items: - $ref: "#/components/schemas/Attachment" - attachments: - type: object - const: {} - example: - bugs: - "1345": - - (attachment) - - (attachment) - attachments: {} - default: - description: "This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get)." - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Attachments - post: - summary: Create attachment on a bug - description: This allows you to add an attachment to a bug in Bugzilla. - parameters: - - $ref: "#/components/parameters/BugId" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - ids: - description: The IDs or aliases of bugs that you want to add this attachment to. The same attachment and comment will be added to all these bugs. - type: array - items: - type: - - string - - integer - data: - description: "The content of the attachment. You must encode it in base64 using an appropriate client library such as ``MIME::Base64`` for Perl." - type: string - format: base64 - file_name: - description: The "file name" that will be displayed in the UI for this attachment and also downloaded copies will be given. - type: string - summary: - description: A short string describing the attachment. - type: string - content_type: - description: "The MIME type of the attachment, like ``text/plain`` or ``image/png``." - type: string - comment: - description: A comment to add along with this attachment. - type: string - is_patch: - description: "``true`` if Bugzilla should treat this attachment as a patch. If you specify this, you do not need to specify a ``content_type``. The ``content_type`` of the attachment will be forced to ``text/plain``. Defaults to ``false`` if not specified." - type: boolean - is_private: - description: '``true`` if the attachment should be private (restricted to the "insidergroup"), ``false`` if the attachment should be public. Defaults to ``false`` if not specified.' - type: boolean - flags: - description: Flags objects to add to the attachment. - type: array - items: - $ref: "#/components/schemas/NewFlag" - bug_flags: - description: Flag objects to add to the attachment's bug. - type: array - items: - $ref: "#/components/schemas/NewFlag" - required: - - ids - - data - - file_name - - summary - - content_type - example: - ids: - - 35 - is_patch: true - comment: This is a new attachment comment - summary: Test Attachment - content_type: text/plain - data: (Some base64 encoded content) - file_name: test_attachment.patch - obsoletes: [] - is_private: false - flags: - - name: review - status: "?" - requestee: user@bugzilla.org - new: true - responses: - "200": - description: Attachment IDs created. - content: - application/json: - schema: - type: object - properties: - ids: - type: array - items: - type: string - example: - ids: - - "2797" - default: - description: | - This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: - - * 129 (Flag Status Invalid) - The flag status is invalid. - * 130 (Flag Modification Denied) - You tried to request, grant, or deny a flag but only a user with the required - permissions may make the change. - * 131 (Flag not Requestable from Specific Person) - You can't ask a specific person for the flag. - * 133 (Flag Type not Unique) - The flag type specified matches several flag types. You must specify - the type id value to update or add a flag. - * 134 (Inactive Flag Type) - The flag type is inactive and cannot be used to create new flags. - * 140 (Markdown Disabled) - You tried to set the "is_markdown" flag of the comment to true but the Markdown feature is not enabled. - * 600 (Attachment Too Large) - You tried to attach a file that was larger than Bugzilla will accept. - * 601 (Invalid MIME Type) - You specified a "content_type" argument that was blank, not a valid - MIME type, or not a MIME type that Bugzilla accepts for attachments. - * 603 (File Name Not Specified) - You did not specify a valid for the "file_name" argument. - * 604 (Summary Required) - You did not specify a value for the "summary" argument. - * 606 (Empty Data) - You set the "data" field to an empty string. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Attachments - "/bug/attachment/{attachment_id}": - get: - summary: Get a specific attachment - description: This allows you to get a specific attachment based on the attachment ID. - parameters: - - name: attachment_id - in: path - description: Integer attachment ID. - required: true - schema: - type: integer - responses: - "200": - description: A single Attachment - content: - application/json: - schema: - type: object - properties: - bugs: - type: object - const: {} - attachments: - description: | - This is an object where the attachment ids point directly to objects describing the individual attachment. - type: object - additionalProperties: - $ref: "#/components/schemas/Attachment" - example: - bugs: {} - attachments: - "234": (attachment) - default: - description: | - This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{bug_id}/get). In addition, it can also throw the following error: - - * 304 (Auth Failure, Attachment is Private) - You specified the id of a private attachment in the "attachment_ids" argument, and you are not in the "insider group" that can see private attachments. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Attachments - put: - summary: Update attachment metadata - description: This allows you to update attachment metadata in Bugzilla. - parameters: - - name: attachment_id - in: path - description: Integer attachment ID. - required: true - schema: - type: integer - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - ids: - description: The IDs of the attachments you want to update. - type: array - items: - type: string - file_name: - description: The "file name" that will be displayed in the UI for this attachment. - type: string - summary: - description: A short string describing the attachment. - type: string - comment: - description: An optional comment to add to the attachment's bug. - type: string - content_type: - description: "The MIME type of the attachment, like ``text/plain`` or ``image/png``." - type: string - is_patch: - description: "``true`` if Bugzilla should treat this attachment as a patch. If you specify this, you do not need to specify a ``content_type``. The ``content_type`` of the attachment will be forced to ``text/plain``." - type: boolean - is_private: - description: "`true` if the attachment should be private, `false` if the attachment should be public." - type: boolean - is_obsolete: - description: "`true` if the attachment is obsolete, `false` otherwise." - type: boolean - flags: - description: An array of Flag objects with changes to the flags. - type: array - items: - $ref: "#/components/schemas/FlagUpdate" - bug_flags: - description: An optional array of Flag objects with changes to the flags of the attachment's bug. - type: array - items: - $ref: "#/components/schemas/FlagUpdate" - required: - - ids - example: - ids: - - 2796 - summary: Test XML file - comment: Changed this from a patch to a XML file - content_type: text/xml - is_patch: 0 - responses: - "200": - description: Attachment metadata updated. - content: - application/json: - schema: - type: object - properties: - attachments: - type: array - items: - type: object - properties: - id: - description: The ID of the attachment that was updated. - type: integer - last_change_time: - description: "The exact time that this update was done at, for this attachment. If no update was done (that is, no fields had their values changed and no comment was added) then this will instead be the last time the attachment was updated." - type: string - format: date-time - changes: - description: "The changes that were actually done on this attachment. The keys are the names of the fields that were changed, and the values are an object with two items:" - type: object - additionalProperties: - type: object - properties: - added: - description: The values that were added to this field. Possibly a comma-and-space-separated list if multiple values were added. - type: string - removed: - description: The values that were removed from this field. - type: string - example: - attachments: - - id: 2796 - last_change_time: "2014-09-29T14:41:53Z" - changes: - content_type: - added: text/xml - removed: text/plain - is_patch: - added: "0" - removed: "1" - summary: - added: Test XML file - removed: test patch - default: - description: | - This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: - - * 129 (Flag Status Invalid) - The flag status is invalid. - * 130 (Flag Modification Denied) - You tried to request, grant, or deny a flag but only a user with the required - permissions may make the change. - * 131 (Flag not Requestable from Specific Person) - You can't ask a specific person for the flag. - * 132 (Flag not Unique) - The flag specified has been set multiple times. You must specify the id - value to update the flag. - * 133 (Flag Type not Unique) - The flag type specified matches several flag types. You must specify - the type id value to update or add a flag. - * 134 (Inactive Flag Type) - The flag type is inactive and cannot be used to create new flags. - * 140 (Markdown Disabled) - You tried to set the "is_markdown" flag of the "comment" to true but Markdown feature is - not enabled. - * 601 (Invalid MIME Type) - You specified a "content_type" argument that was blank, not a valid - MIME type, or not a MIME type that Bugzilla accepts for attachments. - * 603 (File Name Not Specified) - You did not specify a valid for the "file_name" argument. - * 604 (Summary Required) - You did not specify a value for the "summary" argument. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Attachments - "/bug/{id_or_alias}": - get: - summary: Get information about a bug - description: Gets information about a particular bug using its ID or alias. - parameters: - - $ref: "#/components/parameters/BugIdOrAlias" - - name: include_fields - in: query - description: | - Specify the fields to be included in the return value. - - Custom fields are included by default, similar to normal bug fields. To include only custom fields, use `_custom` in include_fields. Extra fields can be retrieved by specifying `_extra` or the field name in include_fields. - schema: - type: array - items: - type: string - responses: - "200": - description: A list of Bugs - content: - application/json: - schema: - type: object - properties: - faults: - type: array - bugs: - type: array - items: - $ref: "#/components/schemas/Bug" - example: - faults: [] - bugs: - - assigned_to_detail: - id: 2 - real_name: Test User - nick: user - name: user@bugzilla.org - email: user@bugzilla.org - flags: - - type_id: 11 - modification_date: "2014-09-28T21:03:47Z" - name: blocker - status: "?" - id: 2906 - setter: user@bugzilla.org - creation_date: "2014-09-28T21:03:47Z" - resolution: INVALID - id: 35 - type: defect - qa_contact: "" - triage_owner: "" - version: "1.0" - status: RESOLVED - creator: user@bugzilla.org - cf_drop_down: "---" - summary: test bug - last_change_time: "2014-09-23T19:12:17Z" - platform: All - url: "" - classification: Unclassified - cc_detail: - - id: 786 - real_name: Foo Bar - nick: foo - name: foo@bar.com - email: foo@bar.com - priority: P1 - is_confirmed: true - creation_time: "2000-07-25T13:50:04Z" - assigned_to: user@bugzilla.org - alias: null - cf_large_text: "" - groups: [] - op_sys: All - cf_bug_id: null - depends_on: [] - is_cc_accessible: true - is_open: false - cf_qa_list_4: "---" - keywords: [] - cc: - - foo@bar.com - see_also: [] - deadline: null - is_creator_accessible: true - whiteboard: "" - dupe_of: null - duplicates: [] - target_milestone: "---" - cf_mulitple_select: [] - component: SaltSprinkler - severity: critical - cf_date: null - product: FoodReplicator - creator_detail: - id: 28 - real_name: hello - nick: namachi - name: user@bugzilla.org - email: namachi@netscape.com - cf_free_text: "" - blocks: [] - regressed_by: [] - regressions: [] - comment_count: 12 - default: - description: | - Various error responses, including: - - * 100 (Invalid Bug Alias) - If you specified an alias and there is no bug with that alias. - * 101 (Invalid Bug ID) - The bug_id you specified doesn't exist in the database. - * 102 (Access Denied) - You do not have access to the bug_id you specified. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Bugs - put: - summary: Update a Bug - description: | - Allows you to update the fields of a bug. Automatically sends emails out about the changes. - parameters: - - $ref: "#/components/parameters/BugIdOrAlias" - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/BugUpdate" - example: - ids: - - 35 - status: IN_PROGRESS - keywords: - add: - - funny - - stupid - responses: - "200": - description: A list of bugs that were updated - content: - application/json: - schema: - type: object - properties: - bugs: - type: array - items: - $ref: "#/components/schemas/UpdatedBug" - example: - bugs: - - alias: null - changes: - keywords: - added: "funny, stupid" - removed: "" - status: - added: IN_PROGRESS - removed: CONFIRMED - id: 35 - last_change_time: "2014-09-29T14:25:35Z" - default: - description: | - This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: - - * 129 (Flag Status Invalid) - The flag status is invalid. - * 130 (Flag Modification Denied) - You tried to request, grant, or deny a flag but only a user with the required - permissions may make the change. - * 131 (Flag not Requestable from Specific Person) - You can't ask a specific person for the flag. - * 132 (Flag not Unique) - The flag specified has been set multiple times. You must specify the id - value to update the flag. - * 133 (Flag Type not Unique) - The flag type specified matches several flag types. You must specify - the type id value to update or add a flag. - * 134 (Inactive Flag Type) - The flag type is inactive and cannot be used to create new flags. - * 140 (Markdown Disabled) - You tried to set the "is_markdown" flag of the "comment" to true but Markdown feature is - not enabled. - * 601 (Invalid MIME Type) - You specified a "content_type" argument that was blank, not a valid - MIME type, or not a MIME type that Bugzilla accepts for attachments. - * 603 (File Name Not Specified) - You did not specify a valid for the "file_name" argument. - * 604 (Summary Required) - You did not specify a value for the "summary" argument. - tags: - - Bugs - "/bug/{id}/history": - get: - summary: Get the history of changes for a specific bug - description: | - Gets the history of changes for a particular bug in the database. You can specify a bug ID or alias and, optionally, a datetime timestamp to only show history since that date. - parameters: - - $ref: "#/components/parameters/BugIdOrAlias" - - name: new_since - in: query - description: A datetime timestamp to only show history since. - schema: - type: string - format: date-time - responses: - "200": - description: A list of bugs with their history - content: - application/json: - schema: - type: object - properties: - bugs: - type: array - items: - $ref: "#/components/schemas/BugWithHistory" - example: - bugs: - - id: 35 - alias: null - history: - - when: "2014-09-23T19:12:17Z" - who: user@bugzilla.org - changes: - - field_name: priority - added: P1 - removed: P2 - - field_name: severity - added: critical - removed: blocker - - when: "2014-09-28T21:03:47Z" - who: user@bugzilla.org - changes: - - field_name: flagtypes.name - added: blocker? - removed: "" - default: - description: | - Same as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Bugs - /bug: - get: - summary: Search for bugs based on particular criteria - description: | - Allows you to search for bugs based on specific criteria. Bugs are returned if they match the criteria specified. Criteria are joined in a logical AND, meaning bugs returned must match all of the specified criteria. - parameters: - - name: alias - in: query - description: The unique alias of this bug. A null value will be returned if this bug has no alias. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: assigned_to - in: query - description: The login name of a user that a bug is assigned to. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: component - in: query - description: "The name of the Component that the bug is in. Note that if there are multiple Components with the same name, and you search for that name, bugs in *all* those Components will be returned. If you don't want this, be sure to also specify the ``product`` argument." - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: count_only - in: query - description: 'If set to true, an object with a single key called "bug_count" will be returned, which is the number of bugs that matched the search.' - schema: - oneOf: - - type: boolean - - type: array - items: - type: boolean - - name: creation_time - in: query - description: Searches for bugs that were created at this time or later. May not be an array. - schema: - type: string - format: date-time - - name: creator - in: query - description: The login name of the user who created the bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: reporter - in: query - description: "The name of the user who reported the bug, for backwards compatibility with older Bugzillas." - schema: - oneOf: - - type: string - - type: array - items: - type: string - deprecated: true - - name: description - in: query - description: The description (initial comment) of the bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: filed_via - in: query - description: Searches for bugs that were created with this method. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: id - in: query - description: The numeric ID of the bug. - schema: - oneOf: - - type: integer - - type: array - items: - type: integer - - name: last_change_time - in: query - description: Searches for bugs that were modified at this time or later. May not be an array. - schema: - type: string - format: date-time - - name: limit - in: query - description: "Limit the number of results returned. If the value is unset, zero or greater than the maximum value set by the administrator, which is 10,000 by default, then the maximum value will be used instead. This is a preventive measure against DoS-like attacks on Bugzilla. Use the ``offset`` argument described below to retrieve more results." - schema: - type: integer - - name: longdescs.count - in: query - description: "The number of comments a bug has. The bug's description is the first comment. For example, to find bugs which someone has commented on after they have been filed, search on ``longdescs.count`` *greater than* 1." - schema: - type: integer - - name: offset - in: query - description: "Used in conjunction with the ``limit`` argument, ``offset`` defines the starting position for the search. For example, given a search that would return 100 bugs, setting ``limit`` to 10 and ``offset`` to 10 would return bugs 11 through 20 from the set of 100." - schema: - type: integer - - name: op_sys - in: query - description: The "Operating System" field of a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: platform - in: query - description: The Platform (sometimes called "Hardware") field of a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: priority - in: query - description: The Priority field on a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: product - in: query - description: The name of the Product that the bug is in. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: quicksearch - in: query - description: Search for bugs using quicksearch syntax. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: resolution - in: query - description: The current resolution--only set if a bug is closed. You can find open bugs by searching for bugs with an empty resolution. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: severity - in: query - description: The Severity field on a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: status - in: query - description: "The current status of a bug (not including its resolution, if it has one, which is a separate field above)." - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: summary - in: query - description: 'Searches for substrings in the single-line Summary field on bugs. If you specify an array, then bugs whose summaries match *any* of the passed substrings will be returned. Note that unlike searching in the Bugzilla UI, substrings are not split on spaces. So searching for ``foo bar`` will match "This is a foo bar" but not "This foo is a bar". ``[''foo'', ''bar'']``, would, however, match the second item.' - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: tags - in: query - description: "Searches for a bug with the specified tag. If you specify an array, then any bugs that match *any* of the tags will be returned. Note that tags are personal to the currently logged in user." - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: target_milestone - in: query - description: 'The Target Milestone field of a bug. Note that even if this Bugzilla does not have the Target Milestone field enabled, you can still search for bugs by Target Milestone. However, it is likely that in tha case, most bugs will not have a Target Milestone set (it defaults to "---" when the field isn''t enabled).' - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: qa_contact - in: query - description: "he login name of the bug's QA Contact. Note that even if this Bugzilla does not have the QA Contact field enabled, you can still search for bugs by QA Contact (though it is likely that no bug will have a QA Contact set, if the field is disabled)." - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: triage_owner - in: query - description: The login name of the Triage Owner of a bug's component. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: type - in: query - description: The Type field on a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: url - in: query - description: The "URL" field of a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: version - in: query - description: The Version field of a bug. - schema: - oneOf: - - type: string - - type: array - items: - type: string - - name: whiteboard - in: query - description: 'Search the "Status Whiteboard" field on bugs for a substring. Works the same as the ``summary`` field described above, but searches the Status Whiteboard field.' - schema: - oneOf: - - type: string - - type: array - items: - type: string - responses: - "200": - description: A list of bugs matching the search criteria - content: - application/json: - schema: - type: object - properties: - bugs: - type: array - items: - $ref: "#/components/schemas/Bug" - example: - bugs: - - id: 35 - alias: null - assigned_to: user@bugzilla.org - component: Widgets - creation_time: "2014-09-23T19:12:17Z" - creator: user@bugzilla.org - description: Bug description goes here. - filed_via: REST API - last_change_time: "2014-09-28T21:03:47Z" - op_sys: All - platform: All - priority: P1 - product: MyProduct - resolution: null - severity: critical - status: NEW - summary: Bug summary goes here. - tags: null - target_milestone: "---" - qa_contact: null - triage_owner: null - type: defect - url: null - version: null - whiteboard: null - longdescs_count: 2 - default: - description: | - If you specify an invalid value for a particular field, you just won’t get any results for that value. - - * 1000 (Parameters Required) - You may not search without any search terms. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Bugs - post: - summary: Create a new bug - description: | - This endpoint allows you to create a new bug in Bugzilla. If you specify any invalid fields, an error will be thrown stating which field is invalid. If you specify any fields you are not allowed to set, they will just be set to their defaults or ignored. - - You cannot currently set all the items here that you can set on enter_bug.cgi. - - The WebService interface may allow you to set things other than those listed here, but realize that anything undocumented here may likely change in the future. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/NewBug" - example: - product: TestProduct - component: TestComponent - version: unspecified - summary: This is a test bug - please disregard - alias: SomeAlias - op_sys: All - priority: P1 - platform: All - type: defect - responses: - "200": - description: A successful bug creation response - content: - application/json: - schema: - type: object - properties: - id: - description: This is the ID of the newly-filed bug. - type: integer - example: - id: 12345 - default: - description: | - Various error responses, including: - - * 51 (Invalid Object) - You specified a field value that is invalid. The error message will have more details. - * 103 (Invalid Alias) - The alias you specified is invalid for some reason. See the error message for more details. - * 104 (Invalid Field) - One of the drop-down fields has an invalid value, or a value entered in a text field is too long. The error message will have more detail. - * 105 (Invalid Component) - You didn't specify a component. - * 106 (Invalid Product) - Either you didn't specify a product, this product doesn't exist, or you don't have permission to enter bugs in this product. - * 107 (Invalid Summary) - You didn't specify a summary for the bug. - * 116 (Dependency Loop) - You specified values in the "blocks" and "depends_on" fields, or the "regressions" and "regressed_by" fields, that would cause a circular dependency between bugs. - * 120 (Group Restriction Denied) - You tried to restrict the bug to a group which does not exist, or which you cannot use with this product. - * 129 (Flag Status Invalid) - The flag status is invalid. - * 130 (Flag Modification Denied) - You tried to request, grant, or deny a flag but only a user with the required permissions may make the change. - * 131 (Flag not Requestable from Specific Person) - You can't ask a specific person for the flag. - * 133 (Flag Type not Unique) - The flag type specified matches several flag types. You must specify the type id value to update or add a flag. - * 134 (Inactive Flag Type) - The flag type is inactive and cannot be used to create new flags. - * 135 (Bug Type Required) - You didn't specify a type for the bug. - * 504 (Invalid User) - Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Bugs - "/bug/{bug_id}/graph": - get: - summary: Return a graph of bug relationships - description: "Return a graph of bug relationships such as dependencies, regressions, and duplicates. By default, resolved bugs are not returned but can be if needed. The bug ID provided will be the root node of the graph." - parameters: - - name: bug_id - in: path - description: The bug ID that will be the root node of the graph. - required: true - schema: - type: integer - - name: ids_only - in: query - description: Do not return simple bug data with each bug ID in the tree. - schema: - type: boolean - default: false - - name: depth - in: query - description: Limit the depth of the graph. - schema: - type: integer - default: 3 - maximum: 9 - - name: show_resolved - in: query - description: Enable if you want to also see RESOLVED bugs in the graph. - schema: - type: boolean - default: false - - name: relationship - in: query - description: "The default is the dependencies graph. To return the graph for other types, pass this parameter." - schema: - type: string - default: dependencies - enum: - - dependencies - - duplicates - - regressions - responses: - "200": - description: | - A graph of bug relationships - - The default return object will be an object with two trees based on the type of relationship selected. For dependencies, it will be ``blocked`` and ``dependson`` For regressions, it will be be ``regresses`` and ``regressed_by``. And for duplicates, it will be ``dupe_of`` and ``dupe``. - content: - application/json: - schema: - oneOf: - - type: object - title: dependencies - properties: - blocked: - $ref: "#/components/schemas/BugNode" - dependson: - $ref: "#/components/schemas/BugNode" - - type: object - title: regressions - properties: - regresses: - $ref: "#/components/schemas/BugNode" - regressed_by: - $ref: "#/components/schemas/BugNode" - - type: object - title: duplicates - properties: - dupe_of: - $ref: "#/components/schemas/BugNode" - dupe: - $ref: "#/components/schemas/BugNode" - example: - blocked: - "2": - "3": - bug: - alias: null - id: 3 - is_confirmed: 1 - op_sys: Unspecified - platform: Unspecified - priority: "--" - resolution: "" - severity: normal - status: NEW - summary: Another new test bug - target_milestone: "---" - type: defect - url: "" - version: unspecified - whiteboard: "" - bug: - alias: null - id: 2 - is_confirmed: 1 - op_sys: Unspecified - platform: Unspecified - priority: "--" - resolution: "" - severity: normal - status: NEW - summary: this is a new test bug - target_milestone: "---" - type: defect - url: "" - version: unspecified - whiteboard: "" - bug: - alias: null - id: 1 - is_confirmed: 1 - op_sys: Unspecified - platform: Unspecified - priority: "--" - resolution: "" - severity: normal - status: NEW - summary: This is a new test bug - target_milestone: "---" - type: defect - url: "" - version: unspecified - whiteboard: "" - dependson: {} - default: - description: Various error responses - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Bugs - /bug/possible_duplicates: - get: - summary: Gets a list of possible duplicate bugs - description: | - Gets a list of possible duplicate bugs based on a given bug ID or bug summary. - parameters: - - name: id - in: query - description: The ID of a bug to find duplicates of. - schema: - type: integer - - name: summary - in: query - description: "A summary to search for duplicates of, only used if no bug ID is given." - schema: - type: string - - name: product - in: query - description: A product group to limit the search in. - schema: - type: string - - name: limit - in: query - description: | - Limit the number of results returned. If the value is unset, zero, or greater than the maximum value set by the administrator (default: 10,000), the maximum value will be used instead. This is a preventive measure against DoS-like attacks on Bugzilla. - schema: - type: integer - responses: - "200": - description: A list of possible duplicate bugs - content: - application/json: - schema: - type: object - properties: - bugs: - type: array - items: - $ref: "#/components/schemas/BugWithHistory" - example: - bugs: - - id: 35 - alias: null - history: - - when: "2014-09-23T19:12:17Z" - who: user@bugzilla.org - changes: - - field_name: priority - added: P1 - removed: P2 - - field_name: severity - added: critical - removed: blocker - - when: "2014-09-28T21:03:47Z" - who: user@bugzilla.org - changes: - - field_name: flagtypes.name - added: blocker? - removed: "" - default: - description: Various error responses - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Bugs - "/bug/{id_or_alias}/comment": - get: - summary: Get all comments for a bug - description: This allows you to get all comments for a particular bug using the bug ID or alias. - parameters: - - $ref: "#/components/parameters/BugIdOrAlias" - - name: new_since - in: query - description: "If specified, the method will only return comments newer than this time." - schema: - type: string - format: date-time - responses: - "200": - description: A list of Comments - content: - application/json: - schema: - type: object - properties: - bugs: - description: | - This is an object, where the keys are the numeric IDs of the bugs, and the value is a object with a single key, comments, which is an array of comments. - type: object - additionalProperties: - type: object - properties: - comments: - type: array - items: - $ref: "#/components/schemas/Comment" - comments: - type: object - example: - bugs: - "35": - comments: - - time: "2000-07-25T13:50:04Z" - text: test bug to fix problem in removing from cc list. - bug_id: 35 - count: 0 - attachment_id: null - is_private: false - tags: [] - creator: user@bugzilla.org - creation_time: "2000-07-25T13:50:04Z" - id: 75 - comments: {} - default: - description: | - Various error responses, including: - - * 100 (Invalid Bug Alias) - If you specified an alias and there is no bug with that alias. - * 101 (Invalid Bug ID) - The bug_id you specified doesn't exist in the database. - * 102 (Access Denied) - You do not have access to the bug_id you specified. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Comments - "/bug/comment/{comment_id}": - get: - summary: Get a specific comment - description: This allows you to get a specific comment based on the comment ID - parameters: - - name: comment_id - in: path - description: A single integer comment ID. - required: true - schema: - type: integer - responses: - "200": - description: A single Comment - content: - application/json: - schema: - type: object - properties: - comments: - description: "This is an object, where the keys are the numeric IDs of the bugs, and the value is a object with a single key, comments, which is an array of comments." - type: object - additionalProperties: - $ref: "#/components/schemas/Comment" - bugs: - type: object - example: - comments: - "75": - time: "2000-07-25T13:50:04Z" - text: test bug to fix problem in removing from cc list. - bug_id: 35 - count: 0 - attachment_id: null - is_private: false - tags: [] - creator: user@bugzilla.org - creation_time: "2000-07-25T13:50:04Z" - id: 75 - bugs: {} - default: - description: | - This method can throw all the same errors as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). In addition, it can also throw the following errors: - - * 110 (Comment Is Private) - You specified the id of a private comment in the "comment_ids" - argument, and you are not in the "insider group" that can see - private comments. - * 111 (Invalid Comment ID) - You specified an id in the "comment_ids" argument that is invalid--either - you specified something that wasn't a number, or there is no comment with - that id. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Comments - "/bug/{id}/comment": - post: - summary: Create a comment on a bug - description: This allows you to add a comment to a bug in Bugzilla. All comments created via the API will be considered Markdown (specifically GitHub Flavored Markdown). - parameters: - - $ref: "#/components/parameters/BugIdOrAlias" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - ids: - description: List of integer bug IDs to add the comment to. - type: array - items: - type: integer - comment: - description: "The comment to append to the bug. If this is empty or all whitespace, an error will be thrown saying that you did not set the ``comment`` parameter." - type: string - is_private: - description: "If set to true, the comment is private, otherwise it is assumed to be public." - type: boolean - is_markdown: - description: "If true, the comment will be rendered as markdown." - type: boolean - default: false - work_time: - description: 'Adds this many hours to the "Hours Worked" on the bug. If you are not in the time tracking group, this value will be ignored.' - type: number - additionalProperties: false - required: - - comment - example: - ids: - - 123 - - 456 - comment: This is an additional comment - is_private: false - is_markdown: true - work_time: 2.5 - responses: - "200": - description: ID of the newly-created comment - content: - application/json: - schema: - type: object - properties: - id: - type: integer - example: - id: 789 - default: - description: | - Various error responses, including: - - * 54 (Hours Worked Too Large) - You specified a "work_time" larger than the maximum allowed value of - "99999.99". - * 100 (Invalid Bug Alias) - If you specified an alias and there is no bug with that alias. - * 101 (Invalid Bug ID) - The id you specified doesn't exist in the database. - * 109 (Bug Edit Denied) - You did not have the necessary rights to edit the bug. - * 113 (Can't Make Private Comments) - You tried to add a private comment, but don't have the necessary rights. - * 114 (Comment Too Long) - You tried to add a comment longer than the maximum allowed length - (65,535 characters). - * 140 (Markdown Disabled) - You tried to set the "is_markdown" flag to true but the Markdown feature - is not enabled. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Comments - "/bug/comment/tags/{query}": - get: - summary: Search for comment tags - description: Searches for tags which contain the provided substring. - parameters: - - name: query - in: path - description: Only tags containing this substring will be returned. - required: true - schema: - type: string - - name: limit - in: query - description: "If provided, will return no more than `limit` tags." - schema: - type: integer - default: 10 - responses: - "200": - description: An array of matching tags - content: - application/json: - schema: - type: array - items: - type: string - example: - - spam - default: - description: | - This method can throw all of the errors that [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) throws, plus: - - * 125 (Comment Tagging Disabled) - Comment tagging support is not available or enabled. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Comments - "/bug/comment/{comment_id}/tags": - put: - summary: Update tags for a comment - description: Adds or removes tags from a comment. - parameters: - - name: comment_id - in: path - description: The ID of the comment to update. - required: true - schema: - type: integer - example: 75 - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - add: - description: The tags to attach to the comment. - type: array - items: - type: string - remove: - description: The tags to detach from the comment. - type: array - items: - type: string - additionalProperties: false - required: - - comment_id - example: - add: - - spam - - bad - responses: - "200": - description: An array of strings containing the comment's updated tags. - content: - application/json: - schema: - type: array - items: - type: string - example: - - bad - - spam - default: - description: | - This method can throw all of the errors that [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) throws, plus: - - * 125 (Comment Tagging Disabled) - Comment tagging support is not available or enabled. - * 126 (Invalid Comment Tag) - The comment tag provided was not valid (e.g. contains invalid characters). - * 127 (Comment Tag Too Short) - The comment tag provided is shorter than the minimum length. - * 128 (Comment Tag Too Long) - The comment tag provided is longer than the maximum length. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Comments - /bug/comment/render: - post: - summary: Render comment as HTML - description: Returns the HTML rendering of the provided comment text. - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - text: - description: Comment text to render. - type: string - id: - description: The ID of the bug to render the comment against. - type: integer - additionalProperties: false - required: - - text - example: - id: 2345 - text: This issue has been fixed in bug 1234. - responses: - "200": - description: Text containing the HTML rendering - content: - application/json: - schema: - type: object - properties: - html: - type: string - example: - html: This issue has been fixed in bug 1234. - default: - description: | - Various error responses, including those thrown by [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - tags: - - Comments -components: - parameters: - BugIdOrAlias: - name: id_or_alias - in: path - description: A single integer bug ID or alias. - required: true - schema: - type: - - string - - integer - schemas: - Attachment: - type: object - properties: - data: - description: "The raw data of the attachment, encoded as Base64." - type: string - format: base64 - size: - description: The length (in bytes) of the attachment. - type: integer - creation_time: - description: The time the attachment was created. - type: string - format: date-time - last_change_time: - description: The last time the attachment was modified. - type: string - format: date-time - id: - description: The numeric ID of the attachment. - type: integer - bug_id: - description: The numeric ID of the bug that the attachment is attached to. - type: integer - file_name: - description: The file name of the attachment. - type: string - summary: - description: A short string describing the attachment. - type: string - content_type: - description: The MIME type of the attachment. - type: string - is_private: - description: '``true`` if the attachment is private (only visible to a certain group called the "insidergroup"), ``false`` otherwise.' - type: boolean - is_obsolete: - description: "``true`` if the attachment is obsolete, ``false`` otherwise." - type: boolean - is_patch: - description: "``true`` if the attachment is a patch, ``false`` otherwise." - type: boolean - creator: - description: The login name of the user that created the attachment. - type: string - creator_detail: - description: An object containing detailed user information for the creator. - $ref: "#/components/schemas/User" - flags: - description: "Array of objects, each containing the information about the flag currently set for each attachment." - type: array - items: - $ref: "#/components/schemas/Flag" - Bug: - type: object - properties: - actual_time: - description: "The total number of hours that this bug has taken so far. If you are not in the time-tracking group, this field will not be included in the return value." - type: number - alias: - description: The unique alias of this bug. A `null` value will be returned if this bug has no alias. - type: - - string - - null - assigned_to: - description: The login name of the user to whom the bug is assigned. - type: string - assigned_to_detail: - $ref: "#/components/schemas/User" - blocks: - description: The IDs of bugs that are "blocked" by this bug. - type: array - items: - type: integer - cc: - description: The login names of users on the CC list of this bug. - type: array - items: - type: string - cc_detail: - description: Array of objects containing detailed user information for each of the cc list members. - type: array - items: - $ref: "#/components/schemas/User" - classification: - description: The name of the current classification the bug is in. - type: string - component: - description: The name of the current component of this bug. - type: string - creation_time: - description: When the bug was created. - type: string - format: date-time - creator: - description: The login name of the person who filed this bug (the reporter). - type: string - creator_detail: - $ref: "#/components/schemas/User" - deadline: - description: "The day that this bug is due to be completed, in the format `YYYY-MM-DD`." - type: string - format: date - depends_on: - description: The IDs of bugs that this bug "depends on". - type: array - items: - type: integer - dupe_of: - description: "The bug ID of the bug that this bug is a duplicate of. If this bug isn't a duplicate of any bug, this will be null." - type: - - integer - - null - duplicates: - description: The ids of bugs that are marked as duplicate of this bug. - type: array - items: - type: integer - estimated_time: - description: "The number of hours that it was estimated that this bug would take. If you are not in the time-tracking group, this field will not be included in the return value." - type: number - flags: - description: An array of objects containing the information about flags currently set for the bug. - type: array - items: - $ref: "#/components/schemas/Flag" - groups: - description: The names of all the groups that this bug is in. - type: array - items: - type: string - id: - description: The unique numeric ID of this bug. - type: integer - is_cc_accessible: - description: "If true, this bug can be accessed by members of the CC list, even if they are not in the groups the bug is restricted to." - type: boolean - is_confirmed: - description: "``true`` if the bug has been confirmed. Usually this means that the bug has at some point been moved out of the ``UNCONFIRMED`` status and into another open status." - type: boolean - is_open: - description: "`true` if this bug is open, ``false`` if it is closed." - type: boolean - is_creator_accessible: - description: "If `true`, this bug can be accessed by the creator of the bug, even if they are not a member of the groups the bug is restricted to." - type: boolean - keywords: - description: Each keyword that is on this bug. - type: array - items: - type: string - last_change_time: - description: When the bug was last changed. - type: string - format: date-time - comment_count: - description: Number of comments associated with the bug. - type: integer - op_sys: - description: The name of the operating system that the bug was filed against. - type: string - platform: - description: The name of the platform (hardware) that the bug was filed against. - type: string - priority: - description: The priority of the bug. - type: string - product: - description: The name of the product this bug is in. - type: string - qa_contact: - description: The login name of the current QA Contact on the bug. - type: string - qa_contact_detail: - description: An object containing detailed user information for the qa_contact. - $ref: "#/components/schemas/User" - regressed_by: - description: The IDs of bugs that introduced this bug. - type: array - items: - type: integer - regressions: - description: The IDs of bugs that are introduced by this bug. - type: array - items: - type: integer - remaining_time: - description: "The number of hours of work remaining until work on this bug is complete. If you are not in the time-tracking group, this field will not be included in the return value." - type: number - resolution: - description: "The current resolution of the bug, or an empty string if the bug is open." - type: string - see_also: - description: The URLs in the See Also field on the bug. - type: array - items: - type: string - severity: - description: The current severity of the bug. - type: string - status: - description: The current status of the bug. - type: string - summary: - description: The summary of this bug. - type: string - target_milestone: - description: "The milestone that this bug is supposed to be fixed by, or for closed bugs, the milestone that it was fixed for." - type: string - type: - description: The type of the bug. - type: string - update_token: - description: The token that you would have to pass to the ``process_bug.cgi`` page in order to update this bug. This changes every time the bug is updated. This field is not returned to logged-out users. - type: string - url: - description: "A URL that demonstrates the problem described in the bug, or is somehow related to the bug report." - type: string - version: - description: The version the bug was reported against. - type: string - whiteboard: - description: The value of the "status whiteboard" field on the bug. - type: string - attachments: - description: | - Each array item is an Attachment object. See [Get Attachment](#tag/Attachments/paths/~1bug~1attachment~1{attachment_id}/get) for details of the object. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: array - items: - $ref: "#/components/schemas/Attachment" - comments: - description: | - Each array item is a Comment object. See [Get Comment](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) for details of the object. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: array - items: - $ref: "#/components/schemas/Comment" - counts: - description: | - An object containing the counts of various items. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: object - properties: - attachments: - description: The number of attachments. - type: integer - cc: - description: The number of carbon copies (CC). - type: integer - comments: - description: The number of comments. - type: integer - keywords: - description: The number of keywords. - type: integer - blocks: - description: The number of blocks. - type: integer - depends_on: - description: The number of dependencies. - type: integer - regressed_by: - description: The number of items causing regression. - type: integer - regressions: - description: The number of regressions. - type: integer - duplicates: - description: The number of duplicate items. - type: integer - description: - description: | - The description (initial comment) of the bug. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: string - filed_via: - description: | - How the bug was filed, e.g. `standard_form`. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: string - history: - description: | - Each array item is a History object. See [Get History](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) for details of the object. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: array - items: - $ref: "#/components/schemas/History" - tags: - description: | - Each array item is a tag name. Note that tags are personal to the currently logged in user and are not the same as comment tags. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: array - items: - type: string - triage_owner: - description: | - The login name of the Triage Owner of the bug's component. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: string - triage_owner_detail: - description: | - An object containing detailed user information for the `triage_owner`. To see the keys included in the user detail object, see below. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: object - last_change_time_non_bot: - description: | - When the bug was last changed human and not a bot. - - > **Note:** - This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. - type: string - format: date-time - additionalProperties: - description: | - Every custom field in this installation will also be included in the return value. Most fields are returned as strings. However, some field types have different return values. - - Normally custom fields are returned by default similar to normal bug fields or you can specify only custom fields by using ``_custom`` in ``include_fields``. - Flag: - type: object - properties: - id: - description: The ID of the flag. - type: integer - name: - description: The name of the flag. - type: string - type_id: - description: The type ID of the flag. - type: integer - creation_date: - description: The timestamp when this flag was originally created. - type: string - format: date-time - modification_date: - description: The timestamp when the flag was last modified. - type: string - format: date-time - status: - description: The current status of the flag. - type: string - setter: - description: The login name of the user who created or last modified the flag. - type: string - requestee: - description: "The login name of the user this flag has been requested to be granted or denied. Note, this field is only returned if a requestee is set." - type: string - User: - type: object - properties: - id: - description: The user ID for this user. - type: integer - real_name: - description: "The 'real' name for this user, if any." - type: string - nick: - description: "The user's nickname. Currently, this is extracted from the real_name, name, or email field." - type: string - name: - description: The user's Bugzilla login. - type: string - email: - description: "The user's email address. Currently, this is the same value as the name." - type: string - BugWithHistory: - type: object - properties: - id: - description: The numeric ID of the bug. - type: integer - alias: - description: The unique alias of this bug. A `null` value will be returned if this bug has no alias. - type: - - string - - null - history: - description: An array of History objects. - type: array - items: - $ref: "#/components/schemas/BugHistory" - BugHistory: - type: object - properties: - when: - description: The date the bug activity/change happened. - type: string - format: date-time - who: - description: The login name of the user who performed the bug change. - type: string - changes: - description: An array of Change objects which contain all the changes that happened to the bug at this time (as specified by ``when``). - type: array - items: - $ref: "#/components/schemas/BugChange" - BugChange: - type: object - properties: - field_name: - description: The name of the bug field that has changed. - type: string - removed: - description: The previous value of the bug field which has been deleted by the change. - type: string - added: - description: The new value of the bug field which has been added by the change. - type: string - attachment_id: - description: "The ID of the attachment that was changed. This only appears if the change was to an attachment, otherwise `attachment_id` will not be present in this object." - type: integer - NewBug: - type: object - properties: - product: - description: The name of the product the bug is being filed against. - type: string - component: - description: The name of a component in the product above. - type: string - summary: - description: A brief description of the bug being filed. - type: string - version: - description: A version of the product above; the version the bug was found in. - type: string - description: - description: (defaulted) The description (initial comment) of the bug. Some Bugzilla installations require this to not be blank. - type: string - filed_via: - description: (defaulted) How the bug is being filed. It will be ``api`` by default when filing through the API. - type: string - op_sys: - description: (defaulted) The operating system the bug was discovered on. - type: string - platform: - description: (defaulted) What type of hardware the bug was experienced on. - type: string - priority: - description: "(defaulted) What order the bug will be fixed in by the developer, compared to the developer's other bugs." - type: string - severity: - description: (defaulted) How severe the bug is. - type: string - type: - description: The basic category of the bug. Some Bugzilla installations require this to be specified. - type: string - alias: - description: The alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla. - type: string - assigned_to: - description: "A user to assign this bug to, if you don't want it to be assigned to the component owner." - type: string - cc: - description: An array of usernames to CC on this bug. - type: array - items: - type: string - comment_is_private: - description: "If set to true, the description is private, otherwise it is assumed to be public." - type: boolean - groups: - description: 'An array of group names to put this bug into. You can see valid group names on the Permissions tab of the Preferences screen, or, if you are an administrator, in the Groups control panel. If you don''t specify this argument, then the bug will be added into all the groups that are set as being "Default" for this product. (If you want to avoid that, you should specify ``groups`` as an empty array.)' - type: array - items: - type: string - qa_contact: - description: "If this installation has QA Contacts enabled, you can set the QA Contact here if you don't want to use the component's default QA Contact." - type: string - status: - description: The status that this bug should start out as. Note that only certain statuses can be set on bug creation. - type: string - resolution: - description: "If you are filing a closed bug, then you will have to specify a resolution. You cannot currently specify a resolution of ``DUPLICATE`` for new bugs, though. That must be done with [Get History](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get)." - type: string - target_milestone: - description: A valid target milestone for this product. - type: string - flags: - type: array - items: - $ref: "#/components/schemas/NewFlag" - keywords: - description: One or more valid keywords to add to this bug. - type: array - items: - type: string - dependson: - description: One or more valid bug ids that this bug depends on. - type: array - items: - type: integer - blocked: - description: One or more valid bug ids that this bug blocks. - type: array - items: - type: integer - regressed_by: - description: One or more valid bug ids that introduced this bug. - type: array - items: - type: integer - additionalProperties: - description: "In addition to the above parameters, if your installation has any custom fields, you can set them just by passing in the name of the field and its value as a string." - required: - - product - - component - - summary - - version - - type - NewFlag: - type: object - properties: - name: - description: The name of the flag type. - type: string - type_id: - description: The internal flag type ID. - type: integer - status: - description: 'The flags new status (i.e. "?", "+", "-" or "X" to clear flag).' - type: string - requestee: - description: The login of the requestee if the flag type is requestable to a specific user. - type: string - BugUpdate: - type: object - properties: - ids: - description: The IDs or aliases of the bugs that you want to modify. - type: array - items: - type: - - integer - - string - alias: - description: The alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla. - type: string - assigned_to: - description: The full login name of the user this bug is assigned to. - type: string - blocks: - description: Bugs that this bug blocks. - type: object - $ref: "#/components/schemas/BugRelationship" - depends_on: - description: Bugs that this bug depends on. - type: object - $ref: "#/components/schemas/BugRelationship" - regressions: - description: Bugs that this bug regresses. - type: object - $ref: "#/components/schemas/BugRelationship" - regressed_by: - description: Bugs that regress this bug. - type: object - $ref: "#/components/schemas/BugRelationship" - cc: - description: The users on the cc list. - type: object - properties: - add: - description: "User names to add to the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name." - type: array - items: - type: string - remove: - description: "User names to remove from the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name." - type: array - items: - type: string - is_cc_accessible: - description: "Whether or not users in the CC list are allowed to access the bug, even if they aren't in a group that can normally access the bug." - type: boolean - comment: - description: A comment on the change. - type: object - properties: - body: - description: The actual text of the comment. - type: string - comment: - description: "An alias for the comment body. (For compatibility with the parameters to [Create Comments](#tag/Comments/paths/~1bug~1{id}~1comment/post))" - type: string - is_private: - description: "Whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown." - type: boolean - comment_is_private: - description: | - This is how you update the privacy of comments that are already on a bug. This is a object, where the keys are the ``int`` ID of comments (not their count on a bug, like #1, #2, #3, but their globally-unique ID, as returned by [Get Comment](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) and the value is a ``boolean`` which specifies whether that comment should become private (``true``) or public (``false``). - - The comment IDs must be valid for the bug being updated. Thus, it is not practical to use this while updating multiple bugs at once, as a single comment ID will never be valid on multiple bugs. - type: object - additionalProperties: - type: boolean - description: Specifies whether that comment should become private (`true`) or public (`false`). - component: - description: The Component the bug is in. - type: string - deadline: - description: "The Deadline field is a date specifying when the bug must be completed by, in the format ``YYYY-MM-DD``." - type: string - format: date - dupe_of: - description: "The bug that this bug is a duplicate of. If you want to mark a bug as a duplicate, the safest thing to do is to set this value and *not* set the ``status`` or ``resolution`` fields. They will automatically be set by Bugzilla to the appropriate values for duplicate bugs." - type: integer - estimated_time: - description: "The total estimate of time required to fix the bug, in hours. This is the *total* estimate, not the amount of time remaining to fix it." - type: number - flags: - description: | - An array of Flag change objects. - - Of any item, at least the status and one of type_id, id, or name must be specified. If a type_id or name matches a single currently set flag, the flag will be updated unless new is specified. - type: array - items: - $ref: "#/components/schemas/FlagUpdate" - groups: - description: The groups a bug is in. - type: object - properties: - add: - description: | - The names of groups to add. Passing in an invalid group name or a group that you cannot add to this bug will cause an error to be thrown. - type: array - items: - type: string - remove: - description: The names of groups to remove. Passing in an invalid group name or a group that you cannot remove from this bug will cause an error to be thrown. - type: array - items: - type: string - keywords: - description: Keywords on the bug. - type: object - properties: - add: - description: The names of keywords to add to the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. - type: array - items: - type: string - remove: - description: The names of keywords to remove from the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. - type: array - items: - type: string - set: - description: "An exact set of keywords to set the field to, on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. Specifying `set` overrides `add` and `remove`." - type: array - items: - type: string - op_sys: - description: The Operating System ("OS") field on the bug. - type: string - platform: - description: The Platform or "Hardware" field on the bug. - type: string - priority: - description: The Priority field on the bug. - type: string - product: - description: | - The name of the product that the bug is in. If you change this, you will probably also want to change ``target_milestone``, ``version``, and ``component``, since those have different legal values in every product. - - If you cannot change the ``target_milestone`` field, it will be reset to the default for the product, when you move a bug to a new product. - - You may also wish to add or remove groups, as which groups are valid on a bug depends on the product. Groups that are not valid in the new product will be automatically removed, and groups which are mandatory in the new product will be automatically added, but no other automatic group changes will be done. - - > **Note:** - Users can only move a bug into a product if they would normally have permission to file new bugs in that product. - type: string - qa_contact: - description: The full login name of the bug's QA Contact. - type: string - is_creator_accessible: - description: Whether or not the bug's reporter is allowed to access the bug. - type: boolean - remaining_time: - description: "How much work time is remaining to fix the bug, in hours. If you set ``work_time`` but don't explicitly set ``remaining_time``, then the ``work_time`` will be deducted from the bug's ``remaining_time``." - type: number - reset_assigned_to: - description: "If true, the `assigned_to` field will be reset to the default for the component that the bug is in. (If you have set the component at the same time as using this, then the component used will be the new component, not the old one.)" - type: boolean - reset_qa_contact: - description: "If true, the ``qa_contact`` field will be reset to the default for the component that the bug is in. (If you have set the component at the same time as using this, then the component used will be the new component, not the old one.)" - type: boolean - resolution: - description: |- - The current resolution. May only be set if you are closing a bug or if you are modifying an already-closed bug. Attempting to set the resolution to *any* value (even an empty or null string) on an open bug will cause an error to be thrown. - > **Note:** If you change the ``status`` field to an open status, the resolution field will automatically be cleared, so you don't have to clear it manually. - type: string - see_also: - description: "The See Also field on a bug, specifying URLs to bugs in other bug trackers." - type: object - properties: - add: - description: "URLs to add to the field. Each URL must be a valid URL to a bug-tracker, or an error will be thrown." - type: array - items: - type: string - remove: - description: URLs to remove from the field. Invalid URLs will be ignored. - type: array - items: - type: string - severity: - description: The Severity field of a bug. - type: string - status: - description: "The status you want to change the bug to. Note that if a bug is changing from open to closed, you should also specify a `resolution`." - type: string - summary: - description: The Summary field of the bug. - type: string - target_milestone: - description: The bug's Target Milestone. - type: string - type: - description: The Type field on the bug. - type: string - url: - description: The "URL" field of a bug. - type: string - version: - description: The bug's Version field. - type: string - whiteboard: - description: The Status Whiteboard field of a bug. - type: string - work_time: - description: "The number of hours worked on this bug as part of this change. If you set ``work_time`` but don't explicitly set ``remaining_time``, then the ``work_time`` will be deducted from the bug's ``remaining_time``." - type: number - additionalProperties: - description: "In addition to the above parameters, if your installation has any custom fields, you can set them just by passing in the name of the field and its value as a string." - required: - - ids - BugRelationship: - type: object - properties: - add: - description: Bug IDs to add to this field. - type: array - items: - type: integer - remove: - description: "Bug IDs to remove from this field. If the bug IDs are not already in the field, they will be ignored." - type: array - items: - type: integer - set: - description: "An exact set of bug IDs to set this field to, overriding the current value. If you specify `set`, then `add` and `remove` will be ignored." - type: array - items: - type: integer - FlagUpdate: - type: object - properties: - name: - description: The name of the flag that will be created or updated. - type: string - type_id: - description: The internal flag type ID that will be created or updated. - type: integer - status: - description: 'The flags new status (i.e. "?", "+", "-" or "X" to clear a flag).' - type: string - requestee: - description: The login of the requestee if the flag type is requestable to a specific user. - type: string - id: - description: Use ID to specify the flag to be updated. - type: integer - new: - description: Set to true if you specifically want a new flag to be created. - type: boolean - required: - - status - UpdatedBug: - type: object - properties: - id: - description: The ID of the bug that was updated. - type: integer - alias: - description: "The alias of the bug that was updated, if this bug has any alias." - type: string - last_change_time: - description: "The exact time that this update was done at, for this bug." - type: string - format: date-time - changes: - type: object - additionalProperties: - $ref: "#/components/schemas/FieldChange" - FieldChange: - type: object - properties: - added: - description: "The values that were added to this field, possibly a comma-and-space-separated list if multiple values were added." - type: string - removed: - description: "The values that were removed from this field, possibly a comma-and-space-separated list if multiple values were removed." - type: string - BugNode: - type: object - properties: - bug: - $ref: "#/components/schemas/Bug" - additionalProperties: - $ref: "#/components/schemas/BugNode" - Comment: - type: object - properties: - id: - description: The globally unique ID for the comment. - type: integer - bug_id: - description: The ID of the bug that this comment is on. - type: integer - attachment_id: - description: "If the comment was made on an attachment, this will be the ID of that attachment. Otherwise it will be null." - type: - - integer - - null - count: - description: "The number of the comment local to the bug. The Description is 0, comments start with 1." - type: integer - text: - description: "The body of the comment, including any special text (such as “this bug was marked as a duplicate of…”)." - type: string - raw_text: - description: The body of the comment without any special additional text. - type: string - creator: - description: The login name of the comment’s author. - type: string - time: - description: The time (in Bugzilla’s timezone) that the comment was added. - type: string - format: date-time - deprecated: true - creation_time: - description: | - This is exactly same as the ``time`` key. Use this field instead of ``time`` for consistency with other methods including [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) and [Get Attachment](#tag/Attachments/paths/~1bug~1attachment~1{attachment_id}/get). - - For compatibility, ``time`` is still usable. However, please note that ``time`` may be deprecated and removed in a future release. - type: string - format: date-time - is_private: - description: '``true`` if this comment is private (only visible to a certain group called the "insidergroup"), ``false`` otherwise.' - type: boolean - is_markdown: - description: '``true`` if this comment is private (only visible to a certain group called the "insidergroup"), ``false``' - type: boolean - Error: - type: object - properties: - error: - description: "When an error occurs over REST, an object is returned with the key error set to true." - const: true - message: - type: string - code: - type: integer - securitySchemes: - X-BUGZILLA-API-KEY: - type: apiKey - description: | - You can specify 'X-BUGZILLA-API-KEY' header with the API key as a value to any request, and you will be authenticated as that user if the key is correct and has not been revoked. - - You can set up an API key by using the [API Keys tab](https://bmo.readthedocs.io/en/latest/using/preferences.html#api-keys) in the Preferences pages. - in: header - name: X-BUGZILLA-API-KEY - Bugzilla_api_key: - type: apiKey - description: | - You can specify an API key via the `Bugzilla_api_key` query parameter, and you will be authenticated as that user if the key is correct and has not been revoked. - - > [!WARNING] - It should be noted that this authentication method is not recommended for use and it is likely to be deprecated in future versions of BMO, due to security concerns. - in: query - name: Bugzilla_api_key - api_key: - type: apiKey - description: | - You can specify an API key via the `api_key` query parameter, and you will be authenticated as that user if the key is correct and has not been revoked. - - > [!WARNING] - It should be noted that this authentication method is not recommended for use and it is likely to be deprecated in future versions of BMO, due to security concerns. - in: query - name: api_key -tags: - - name: Attachments - description: "The Bugzilla API for creating, changing, and getting the details of attachments." - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/attachment.html" - - name: Bugs - description: This part of the Bugzilla REST API allows you to file new bugs in Bugzilla and to get information about existing bugs. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/bug.html" - - name: Bug User Last Visited - description: Update the last-visited time for the specified bug and current user. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/bug-user-last-visit.html" - - name: Bugzilla Information - description: These methods are used to get general configuration information about this Bugzilla instance. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/bugzilla.html" - - name: Classifications - description: This part of the Bugzilla API allows you to deal with the available classifications. You will be able to get information about them as well as manipulate them. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/classification.html" - - name: Comments - description: "This allows you to get data about comments, given a bug ID or comment ID." - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html" - - name: Components - description: This part of the Bugzilla API looks at individual components and also allows updating their information. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/component.html" - - name: Bug Fields - description: The Bugzilla API for getting details about bug fields. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/field.html" - - name: Flag Activity - description: This API provides information about activity relating to bug and attachment flags. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/flag-activity.html" - - name: General - description: This is the standard REST API for external programs that want to interact with Bugzilla. It provides a REST interface to various Bugzilla functions. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/general.html" - - name: Github - description: | - This API endpoint is for creating attachments in a bug that are redirect links to a - specific Github pull request. This allows a bug viewer to click on the Github link - and be automatically redirected to the pull request. - - **Github Setup Instructions** - - * From the repository main page, click on the Settings tab. - * Click on Webhooks from the left side menu. - * Click on the Add Webhook button near the top right. - * For the payload url, enter ``https://bugzilla.mozilla.org/rest/github/pull_request``. - * Choose ``application/json`` for the content type. - * You will need to enter the signature secret obtained from a BMO admin (DO NOT SHARE). - * Make sure Enable SSL is turned on. - * Select "Let me select individual events" and only enable changes for "Pull Requests". - * Make sure at the bottom that "Active" is checked on. - * Save the webhook. - - > **Note:** - Past pull requests will not automatically get a link created in the bug. New pull - requests should get the link automatically when the pull request is first created. - - > **Note:** - The API endpoint looks at the pull request title for the bug id so - make sure the title is formatted correctly to allow the bug id to be determined. - Examples are: ``Bug 1234:``, ``Bug - 1234``, ``bug 1234``, or ``Bug 1234 -``. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/github.html" - - name: Groups - description: "The API for creating, changing, and getting information about groups." - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/group.html" - - name: Products - description: This part of the Bugzilla API allows you to list the available products and get information about them. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/product.html" - - name: Users - description: "This part of the Bugzilla API allows you to create user accounts, get information about user accounts and to log in or out using an existing account." - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/api/core/v1/user.html" - - name: Webhooks - description: These methods are used to access information about and update your configured webhooks. - externalDocs: - url: "https://bmo.readthedocs.io/en/latest/extensions/Webhooks/api/v1/webhooks.html#list" -externalDocs: - description: Sphinx WebService API Reference - url: "https://bugzilla.readthedocs.io/en/latest/api/" diff --git a/openapi/components/parameters/BugIdOrAlias.yaml b/openapi/components/parameters/BugIdOrAlias.yaml new file mode 100644 index 0000000000..5917eb3c09 --- /dev/null +++ b/openapi/components/parameters/BugIdOrAlias.yaml @@ -0,0 +1,8 @@ +name: id_or_alias +in: path +description: A single integer bug ID or alias. +required: true +schema: + type: + - string + - integer diff --git a/openapi/components/schemas/Attachment.yaml b/openapi/components/schemas/Attachment.yaml new file mode 100644 index 0000000000..f0fcc3fe40 --- /dev/null +++ b/openapi/components/schemas/Attachment.yaml @@ -0,0 +1,56 @@ +type: object +properties: + data: + description: The raw data of the attachment, encoded as Base64. + type: string + format: base64 + size: + description: The length (in bytes) of the attachment. + type: integer + creation_time: + description: The time the attachment was created. + type: string + format: date-time + last_change_time: + description: The last time the attachment was modified. + type: string + format: date-time + id: + description: The numeric ID of the attachment. + type: integer + bug_id: + description: The numeric ID of the bug that the attachment is attached to. + type: integer + file_name: + description: The file name of the attachment. + type: string + summary: + description: A short string describing the attachment. + type: string + content_type: + description: The MIME type of the attachment. + type: string + is_private: + description: >- + ``true`` if the attachment is private (only visible to a certain group + called the "insidergroup"), ``false`` otherwise. + type: boolean + is_obsolete: + description: '``true`` if the attachment is obsolete, ``false`` otherwise.' + type: boolean + is_patch: + description: '``true`` if the attachment is a patch, ``false`` otherwise.' + type: boolean + creator: + description: The login name of the user that created the attachment. + type: string + creator_detail: + description: An object containing detailed user information for the creator. + $ref: ./User.yaml + flags: + description: >- + Array of objects, each containing the information about the flag currently + set for each attachment. + type: array + items: + $ref: ./Flag.yaml diff --git a/openapi/components/schemas/Bug.yaml b/openapi/components/schemas/Bug.yaml new file mode 100644 index 0000000000..6d0438398e --- /dev/null +++ b/openapi/components/schemas/Bug.yaml @@ -0,0 +1,331 @@ +type: object +properties: + actual_time: + description: >- + The total number of hours that this bug has taken so far. If you are not + in the time-tracking group, this field will not be included in the return + value. + type: number + alias: + description: >- + The unique alias of this bug. A `null` value will be returned if this bug + has no alias. + type: + - string + - null + assigned_to: + description: The login name of the user to whom the bug is assigned. + type: string + assigned_to_detail: + $ref: ./User.yaml + blocks: + description: The IDs of bugs that are "blocked" by this bug. + type: array + items: + type: integer + cc: + description: The login names of users on the CC list of this bug. + type: array + items: + type: string + cc_detail: + description: >- + Array of objects containing detailed user information for each of the cc + list members. + type: array + items: + $ref: ./User.yaml + classification: + description: The name of the current classification the bug is in. + type: string + component: + description: The name of the current component of this bug. + type: string + creation_time: + description: When the bug was created. + type: string + format: date-time + creator: + description: The login name of the person who filed this bug (the reporter). + type: string + creator_detail: + $ref: ./User.yaml + deadline: + description: The day that this bug is due to be completed, in the format `YYYY-MM-DD`. + type: string + format: date + depends_on: + description: The IDs of bugs that this bug "depends on". + type: array + items: + type: integer + dupe_of: + description: >- + The bug ID of the bug that this bug is a duplicate of. If this bug isn't a + duplicate of any bug, this will be null. + type: + - integer + - null + duplicates: + description: The ids of bugs that are marked as duplicate of this bug. + type: array + items: + type: integer + estimated_time: + description: >- + The number of hours that it was estimated that this bug would take. If you + are not in the time-tracking group, this field will not be included in the + return value. + type: number + flags: + description: >- + An array of objects containing the information about flags currently set + for the bug. + type: array + items: + $ref: ./Flag.yaml + groups: + description: The names of all the groups that this bug is in. + type: array + items: + type: string + id: + description: The unique numeric ID of this bug. + type: integer + is_cc_accessible: + description: >- + If true, this bug can be accessed by members of the CC list, even if they + are not in the groups the bug is restricted to. + type: boolean + is_confirmed: + description: >- + ``true`` if the bug has been confirmed. Usually this means that the bug + has at some point been moved out of the ``UNCONFIRMED`` status and into + another open status. + type: boolean + is_open: + description: '`true` if this bug is open, ``false`` if it is closed.' + type: boolean + is_creator_accessible: + description: >- + If `true`, this bug can be accessed by the creator of the bug, even if + they are not a member of the groups the bug is restricted to. + type: boolean + keywords: + description: Each keyword that is on this bug. + type: array + items: + type: string + last_change_time: + description: When the bug was last changed. + type: string + format: date-time + comment_count: + description: Number of comments associated with the bug. + type: integer + op_sys: + description: The name of the operating system that the bug was filed against. + type: string + platform: + description: The name of the platform (hardware) that the bug was filed against. + type: string + priority: + description: The priority of the bug. + type: string + product: + description: The name of the product this bug is in. + type: string + qa_contact: + description: The login name of the current QA Contact on the bug. + type: string + qa_contact_detail: + description: An object containing detailed user information for the qa_contact. + $ref: ./User.yaml + regressed_by: + description: The IDs of bugs that introduced this bug. + type: array + items: + type: integer + regressions: + description: The IDs of bugs that are introduced by this bug. + type: array + items: + type: integer + remaining_time: + description: >- + The number of hours of work remaining until work on this bug is complete. + If you are not in the time-tracking group, this field will not be included + in the return value. + type: number + resolution: + description: The current resolution of the bug, or an empty string if the bug is open. + type: string + see_also: + description: The URLs in the See Also field on the bug. + type: array + items: + type: string + severity: + description: The current severity of the bug. + type: string + status: + description: The current status of the bug. + type: string + summary: + description: The summary of this bug. + type: string + target_milestone: + description: >- + The milestone that this bug is supposed to be fixed by, or for closed + bugs, the milestone that it was fixed for. + type: string + type: + description: The type of the bug. + type: string + update_token: + description: >- + The token that you would have to pass to the ``process_bug.cgi`` page in + order to update this bug. This changes every time the bug is updated. This + field is not returned to logged-out users. + type: string + url: + description: >- + A URL that demonstrates the problem described in the bug, or is somehow + related to the bug report. + type: string + version: + description: The version the bug was reported against. + type: string + whiteboard: + description: The value of the "status whiteboard" field on the bug. + type: string + attachments: + description: > + Each array item is an Attachment object. See [Get + Attachment](#tag/Attachments/paths/~1bug~1attachment~1{attachment_id}/get) + for details of the object. + + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + $ref: ./Attachment.yaml + comments: + description: > + Each array item is a Comment object. See [Get + Comment](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) for details + of the object. + + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + $ref: ./Comment.yaml + counts: + description: | + An object containing the counts of various items. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: object + properties: + attachments: + description: The number of attachments. + type: integer + cc: + description: The number of carbon copies (CC). + type: integer + comments: + description: The number of comments. + type: integer + keywords: + description: The number of keywords. + type: integer + blocks: + description: The number of blocks. + type: integer + depends_on: + description: The number of dependencies. + type: integer + regressed_by: + description: The number of items causing regression. + type: integer + regressions: + description: The number of regressions. + type: integer + duplicates: + description: The number of duplicate items. + type: integer + description: + description: | + The description (initial comment) of the bug. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + filed_via: + description: | + How the bug was filed, e.g. `standard_form`. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + history: + description: > + Each array item is a History object. See [Get + History](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) for details + of the object. + + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + $ref: '#/components/schemas/History' + tags: + description: > + Each array item is a tag name. Note that tags are personal to the + currently logged in user and are not the same as comment tags. + + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: array + items: + type: string + triage_owner: + description: | + The login name of the Triage Owner of the bug's component. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + triage_owner_detail: + description: > + An object containing detailed user information for the `triage_owner`. To + see the keys included in the user detail object, see below. + + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: object + last_change_time_non_bot: + description: | + When the bug was last changed human and not a bot. + + > **Note:** + This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. + type: string + format: date-time +additionalProperties: + description: > + Every custom field in this installation will also be included in the return + value. Most fields are returned as strings. However, some field types have + different return values. + + + Normally custom fields are returned by default similar to normal bug fields + or you can specify only custom fields by using ``_custom`` in + ``include_fields``. diff --git a/openapi/components/schemas/BugChange.yaml b/openapi/components/schemas/BugChange.yaml new file mode 100644 index 0000000000..8e2c023c11 --- /dev/null +++ b/openapi/components/schemas/BugChange.yaml @@ -0,0 +1,17 @@ +type: object +properties: + field_name: + description: The name of the bug field that has changed. + type: string + removed: + description: The previous value of the bug field which has been deleted by the change. + type: string + added: + description: The new value of the bug field which has been added by the change. + type: string + attachment_id: + description: >- + The ID of the attachment that was changed. This only appears if the change + was to an attachment, otherwise `attachment_id` will not be present in + this object. + type: integer diff --git a/openapi/components/schemas/BugHistory.yaml b/openapi/components/schemas/BugHistory.yaml new file mode 100644 index 0000000000..7111545379 --- /dev/null +++ b/openapi/components/schemas/BugHistory.yaml @@ -0,0 +1,16 @@ +type: object +properties: + when: + description: The date the bug activity/change happened. + type: string + format: date-time + who: + description: The login name of the user who performed the bug change. + type: string + changes: + description: >- + An array of Change objects which contain all the changes that happened to + the bug at this time (as specified by ``when``). + type: array + items: + $ref: ./BugChange.yaml diff --git a/openapi/components/schemas/BugNode.yaml b/openapi/components/schemas/BugNode.yaml new file mode 100644 index 0000000000..7ff1df9d04 --- /dev/null +++ b/openapi/components/schemas/BugNode.yaml @@ -0,0 +1,6 @@ +type: object +properties: + bug: + $ref: ./Bug.yaml + additionalProperties: + $ref: ./BugNode.yaml diff --git a/openapi/components/schemas/BugRelationship.yaml b/openapi/components/schemas/BugRelationship.yaml new file mode 100644 index 0000000000..31015c1bcc --- /dev/null +++ b/openapi/components/schemas/BugRelationship.yaml @@ -0,0 +1,21 @@ +type: object +properties: + add: + description: Bug IDs to add to this field. + type: array + items: + type: integer + remove: + description: >- + Bug IDs to remove from this field. If the bug IDs are not already in the + field, they will be ignored. + type: array + items: + type: integer + set: + description: >- + An exact set of bug IDs to set this field to, overriding the current + value. If you specify `set`, then `add` and `remove` will be ignored. + type: array + items: + type: integer diff --git a/openapi/components/schemas/BugUpdate.yaml b/openapi/components/schemas/BugUpdate.yaml new file mode 100644 index 0000000000..221190585e --- /dev/null +++ b/openapi/components/schemas/BugUpdate.yaml @@ -0,0 +1,296 @@ +type: object +properties: + ids: + description: The IDs or aliases of the bugs that you want to modify. + type: array + items: + type: + - integer + - string + alias: + description: >- + The alias for the bug that can be used instead of a bug number when + accessing this bug. Must be unique in all of this Bugzilla. + type: string + assigned_to: + description: The full login name of the user this bug is assigned to. + type: string + blocks: + description: Bugs that this bug blocks. + type: object + $ref: ./BugRelationship.yaml + depends_on: + description: Bugs that this bug depends on. + type: object + $ref: ./BugRelationship.yaml + regressions: + description: Bugs that this bug regresses. + type: object + $ref: ./BugRelationship.yaml + regressed_by: + description: Bugs that regress this bug. + type: object + $ref: ./BugRelationship.yaml + cc: + description: The users on the cc list. + type: object + properties: + add: + description: >- + User names to add to the CC list. They must be full user names, and an + error will be thrown if you pass in an invalid user name. + type: array + items: + type: string + remove: + description: >- + User names to remove from the CC list. They must be full user names, + and an error will be thrown if you pass in an invalid user name. + type: array + items: + type: string + is_cc_accessible: + description: >- + Whether or not users in the CC list are allowed to access the bug, even if + they aren't in a group that can normally access the bug. + type: boolean + comment: + description: A comment on the change. + type: object + properties: + body: + description: The actual text of the comment. + type: string + comment: + description: >- + An alias for the comment body. (For compatibility with the parameters + to [Create Comments](#tag/Comments/paths/~1bug~1{id}~1comment/post)) + type: string + is_private: + description: >- + Whether the comment is private or not. If you try to make a comment + private and you don't have the permission to, an error will be thrown. + type: boolean + comment_is_private: + description: > + This is how you update the privacy of comments that are already on a bug. + This is a object, where the keys are the ``int`` ID of comments (not their + count on a bug, like #1, #2, #3, but their globally-unique ID, as returned + by [Get Comment](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get) and + the value is a ``boolean`` which specifies whether that comment should + become private (``true``) or public (``false``). + + + The comment IDs must be valid for the bug being updated. Thus, it is not + practical to use this while updating multiple bugs at once, as a single + comment ID will never be valid on multiple bugs. + type: object + additionalProperties: + type: boolean + description: >- + Specifies whether that comment should become private (`true`) or public + (`false`). + component: + description: The Component the bug is in. + type: string + deadline: + description: >- + The Deadline field is a date specifying when the bug must be completed by, + in the format ``YYYY-MM-DD``. + type: string + format: date + dupe_of: + description: >- + The bug that this bug is a duplicate of. If you want to mark a bug as a + duplicate, the safest thing to do is to set this value and *not* set the + ``status`` or ``resolution`` fields. They will automatically be set by + Bugzilla to the appropriate values for duplicate bugs. + type: integer + estimated_time: + description: >- + The total estimate of time required to fix the bug, in hours. This is the + *total* estimate, not the amount of time remaining to fix it. + type: number + flags: + description: > + An array of Flag change objects. + + + Of any item, at least the status and one of type_id, id, or name must be + specified. If a type_id or name matches a single currently set flag, the + flag will be updated unless new is specified. + type: array + items: + $ref: ./FlagUpdate.yaml + groups: + description: The groups a bug is in. + type: object + properties: + add: + description: > + The names of groups to add. Passing in an invalid group name or a + group that you cannot add to this bug will cause an error to be + thrown. + type: array + items: + type: string + remove: + description: >- + The names of groups to remove. Passing in an invalid group name or a + group that you cannot remove from this bug will cause an error to be + thrown. + type: array + items: + type: string + keywords: + description: Keywords on the bug. + type: object + properties: + add: + description: >- + The names of keywords to add to the field on the bug. Passing + something that isn't a valid keyword name will cause an error to be + thrown. + type: array + items: + type: string + remove: + description: >- + The names of keywords to remove from the field on the bug. Passing + something that isn't a valid keyword name will cause an error to be + thrown. + type: array + items: + type: string + set: + description: >- + An exact set of keywords to set the field to, on the bug. Passing + something that isn't a valid keyword name will cause an error to be + thrown. Specifying `set` overrides `add` and `remove`. + type: array + items: + type: string + op_sys: + description: The Operating System ("OS") field on the bug. + type: string + platform: + description: The Platform or "Hardware" field on the bug. + type: string + priority: + description: The Priority field on the bug. + type: string + product: + description: > + The name of the product that the bug is in. If you change this, you will + probably also want to change ``target_milestone``, ``version``, and + ``component``, since those have different legal values in every product. + + + If you cannot change the ``target_milestone`` field, it will be reset to + the default for the product, when you move a bug to a new product. + + + You may also wish to add or remove groups, as which groups are valid on a + bug depends on the product. Groups that are not valid in the new product + will be automatically removed, and groups which are mandatory in the new + product will be automatically added, but no other automatic group changes + will be done. + + + > **Note:** + Users can only move a bug into a product if they would normally have permission to file new bugs in that product. + type: string + qa_contact: + description: The full login name of the bug's QA Contact. + type: string + is_creator_accessible: + description: Whether or not the bug's reporter is allowed to access the bug. + type: boolean + remaining_time: + description: >- + How much work time is remaining to fix the bug, in hours. If you set + ``work_time`` but don't explicitly set ``remaining_time``, then the + ``work_time`` will be deducted from the bug's ``remaining_time``. + type: number + reset_assigned_to: + description: >- + If true, the `assigned_to` field will be reset to the default for the + component that the bug is in. (If you have set the component at the same + time as using this, then the component used will be the new component, not + the old one.) + type: boolean + reset_qa_contact: + description: >- + If true, the ``qa_contact`` field will be reset to the default for the + component that the bug is in. (If you have set the component at the same + time as using this, then the component used will be the new component, not + the old one.) + type: boolean + resolution: + description: >- + The current resolution. May only be set if you are closing a bug or if you + are modifying an already-closed bug. Attempting to set the resolution to + *any* value (even an empty or null string) on an open bug will cause an + error to be thrown. + + > **Note:** If you change the ``status`` field to an open status, the + resolution field will automatically be cleared, so you don't have to clear + it manually. + type: string + see_also: + description: >- + The See Also field on a bug, specifying URLs to bugs in other bug + trackers. + type: object + properties: + add: + description: >- + URLs to add to the field. Each URL must be a valid URL to a + bug-tracker, or an error will be thrown. + type: array + items: + type: string + remove: + description: URLs to remove from the field. Invalid URLs will be ignored. + type: array + items: + type: string + severity: + description: The Severity field of a bug. + type: string + status: + description: >- + The status you want to change the bug to. Note that if a bug is changing + from open to closed, you should also specify a `resolution`. + type: string + summary: + description: The Summary field of the bug. + type: string + target_milestone: + description: The bug's Target Milestone. + type: string + type: + description: The Type field on the bug. + type: string + url: + description: The "URL" field of a bug. + type: string + version: + description: The bug's Version field. + type: string + whiteboard: + description: The Status Whiteboard field of a bug. + type: string + work_time: + description: >- + The number of hours worked on this bug as part of this change. If you set + ``work_time`` but don't explicitly set ``remaining_time``, then the + ``work_time`` will be deducted from the bug's ``remaining_time``. + type: number +additionalProperties: + description: >- + In addition to the above parameters, if your installation has any custom + fields, you can set them just by passing in the name of the field and its + value as a string. +required: + - ids diff --git a/openapi/components/schemas/BugWithHistory.yaml b/openapi/components/schemas/BugWithHistory.yaml new file mode 100644 index 0000000000..92124cb4b3 --- /dev/null +++ b/openapi/components/schemas/BugWithHistory.yaml @@ -0,0 +1,17 @@ +type: object +properties: + id: + description: The numeric ID of the bug. + type: integer + alias: + description: >- + The unique alias of this bug. A `null` value will be returned if this bug + has no alias. + type: + - string + - null + history: + description: An array of History objects. + type: array + items: + $ref: ./BugHistory.yaml diff --git a/openapi/components/schemas/Comment.yaml b/openapi/components/schemas/Comment.yaml new file mode 100644 index 0000000000..64608896c6 --- /dev/null +++ b/openapi/components/schemas/Comment.yaml @@ -0,0 +1,58 @@ +type: object +properties: + id: + description: The globally unique ID for the comment. + type: integer + bug_id: + description: The ID of the bug that this comment is on. + type: integer + attachment_id: + description: >- + If the comment was made on an attachment, this will be the ID of that + attachment. Otherwise it will be null. + type: + - integer + - null + count: + description: >- + The number of the comment local to the bug. The Description is 0, comments + start with 1. + type: integer + text: + description: >- + The body of the comment, including any special text (such as “this bug was + marked as a duplicate of…”). + type: string + raw_text: + description: The body of the comment without any special additional text. + type: string + creator: + description: The login name of the comment’s author. + type: string + time: + description: The time (in Bugzilla’s timezone) that the comment was added. + type: string + format: date-time + deprecated: true + creation_time: + description: > + This is exactly same as the ``time`` key. Use this field instead of + ``time`` for consistency with other methods including [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) and [Get + Attachment](#tag/Attachments/paths/~1bug~1attachment~1{attachment_id}/get). + + + For compatibility, ``time`` is still usable. However, please note that + ``time`` may be deprecated and removed in a future release. + type: string + format: date-time + is_private: + description: >- + ``true`` if this comment is private (only visible to a certain group + called the "insidergroup"), ``false`` otherwise. + type: boolean + is_markdown: + description: >- + ``true`` if this comment is private (only visible to a certain group + called the "insidergroup"), ``false`` + type: boolean diff --git a/openapi/components/schemas/Error.yaml b/openapi/components/schemas/Error.yaml new file mode 100644 index 0000000000..2159ea5ef5 --- /dev/null +++ b/openapi/components/schemas/Error.yaml @@ -0,0 +1,11 @@ +type: object +properties: + error: + description: >- + When an error occurs over REST, an object is returned with the key error + set to true. + const: true + message: + type: string + code: + type: integer diff --git a/openapi/components/schemas/FieldChange.yaml b/openapi/components/schemas/FieldChange.yaml new file mode 100644 index 0000000000..bbf83c1c1f --- /dev/null +++ b/openapi/components/schemas/FieldChange.yaml @@ -0,0 +1,12 @@ +type: object +properties: + added: + description: >- + The values that were added to this field, possibly a + comma-and-space-separated list if multiple values were added. + type: string + removed: + description: >- + The values that were removed from this field, possibly a + comma-and-space-separated list if multiple values were removed. + type: string diff --git a/openapi/components/schemas/Flag.yaml b/openapi/components/schemas/Flag.yaml new file mode 100644 index 0000000000..1912e9f87d --- /dev/null +++ b/openapi/components/schemas/Flag.yaml @@ -0,0 +1,30 @@ +type: object +properties: + id: + description: The ID of the flag. + type: integer + name: + description: The name of the flag. + type: string + type_id: + description: The type ID of the flag. + type: integer + creation_date: + description: The timestamp when this flag was originally created. + type: string + format: date-time + modification_date: + description: The timestamp when the flag was last modified. + type: string + format: date-time + status: + description: The current status of the flag. + type: string + setter: + description: The login name of the user who created or last modified the flag. + type: string + requestee: + description: >- + The login name of the user this flag has been requested to be granted or + denied. Note, this field is only returned if a requestee is set. + type: string diff --git a/openapi/components/schemas/FlagUpdate.yaml b/openapi/components/schemas/FlagUpdate.yaml new file mode 100644 index 0000000000..dd80e3660d --- /dev/null +++ b/openapi/components/schemas/FlagUpdate.yaml @@ -0,0 +1,24 @@ +type: object +properties: + name: + description: The name of the flag that will be created or updated. + type: string + type_id: + description: The internal flag type ID that will be created or updated. + type: integer + status: + description: The flags new status (i.e. "?", "+", "-" or "X" to clear a flag). + type: string + requestee: + description: >- + The login of the requestee if the flag type is requestable to a specific + user. + type: string + id: + description: Use ID to specify the flag to be updated. + type: integer + new: + description: Set to true if you specifically want a new flag to be created. + type: boolean +required: + - status diff --git a/openapi/components/schemas/NewBug.yaml b/openapi/components/schemas/NewBug.yaml new file mode 100644 index 0000000000..9b8624f4fe --- /dev/null +++ b/openapi/components/schemas/NewBug.yaml @@ -0,0 +1,129 @@ +type: object +properties: + product: + description: The name of the product the bug is being filed against. + type: string + component: + description: The name of a component in the product above. + type: string + summary: + description: A brief description of the bug being filed. + type: string + version: + description: A version of the product above; the version the bug was found in. + type: string + description: + description: >- + (defaulted) The description (initial comment) of the bug. Some Bugzilla + installations require this to not be blank. + type: string + filed_via: + description: >- + (defaulted) How the bug is being filed. It will be ``api`` by default when + filing through the API. + type: string + op_sys: + description: (defaulted) The operating system the bug was discovered on. + type: string + platform: + description: (defaulted) What type of hardware the bug was experienced on. + type: string + priority: + description: >- + (defaulted) What order the bug will be fixed in by the developer, compared + to the developer's other bugs. + type: string + severity: + description: (defaulted) How severe the bug is. + type: string + type: + description: >- + The basic category of the bug. Some Bugzilla installations require this to + be specified. + type: string + alias: + description: >- + The alias for the bug that can be used instead of a bug number when + accessing this bug. Must be unique in all of this Bugzilla. + type: string + assigned_to: + description: >- + A user to assign this bug to, if you don't want it to be assigned to the + component owner. + type: string + cc: + description: An array of usernames to CC on this bug. + type: array + items: + type: string + comment_is_private: + description: >- + If set to true, the description is private, otherwise it is assumed to be + public. + type: boolean + groups: + description: >- + An array of group names to put this bug into. You can see valid group + names on the Permissions tab of the Preferences screen, or, if you are an + administrator, in the Groups control panel. If you don't specify this + argument, then the bug will be added into all the groups that are set as + being "Default" for this product. (If you want to avoid that, you should + specify ``groups`` as an empty array.) + type: array + items: + type: string + qa_contact: + description: >- + If this installation has QA Contacts enabled, you can set the QA Contact + here if you don't want to use the component's default QA Contact. + type: string + status: + description: >- + The status that this bug should start out as. Note that only certain + statuses can be set on bug creation. + type: string + resolution: + description: >- + If you are filing a closed bug, then you will have to specify a + resolution. You cannot currently specify a resolution of ``DUPLICATE`` + for new bugs, though. That must be done with [Get + History](#tag/Comments/paths/~1bug~1comment~1{comment_id}/get). + type: string + target_milestone: + description: A valid target milestone for this product. + type: string + flags: + type: array + items: + $ref: ./NewFlag.yaml + keywords: + description: One or more valid keywords to add to this bug. + type: array + items: + type: string + dependson: + description: One or more valid bug ids that this bug depends on. + type: array + items: + type: integer + blocked: + description: One or more valid bug ids that this bug blocks. + type: array + items: + type: integer + regressed_by: + description: One or more valid bug ids that introduced this bug. + type: array + items: + type: integer +additionalProperties: + description: >- + In addition to the above parameters, if your installation has any custom + fields, you can set them just by passing in the name of the field and its + value as a string. +required: + - product + - component + - summary + - version + - type diff --git a/openapi/components/schemas/NewFlag.yaml b/openapi/components/schemas/NewFlag.yaml new file mode 100644 index 0000000000..5af7d26d7e --- /dev/null +++ b/openapi/components/schemas/NewFlag.yaml @@ -0,0 +1,16 @@ +type: object +properties: + name: + description: The name of the flag type. + type: string + type_id: + description: The internal flag type ID. + type: integer + status: + description: The flags new status (i.e. "?", "+", "-" or "X" to clear flag). + type: string + requestee: + description: >- + The login of the requestee if the flag type is requestable to a specific + user. + type: string diff --git a/openapi/components/schemas/UpdatedBug.yaml b/openapi/components/schemas/UpdatedBug.yaml new file mode 100644 index 0000000000..2f3e7b6230 --- /dev/null +++ b/openapi/components/schemas/UpdatedBug.yaml @@ -0,0 +1,16 @@ +type: object +properties: + id: + description: The ID of the bug that was updated. + type: integer + alias: + description: The alias of the bug that was updated, if this bug has any alias. + type: string + last_change_time: + description: The exact time that this update was done at, for this bug. + type: string + format: date-time + changes: + type: object + additionalProperties: + $ref: ./FieldChange.yaml diff --git a/openapi/components/schemas/User.yaml b/openapi/components/schemas/User.yaml new file mode 100644 index 0000000000..560ef544aa --- /dev/null +++ b/openapi/components/schemas/User.yaml @@ -0,0 +1,19 @@ +type: object +properties: + id: + description: The user ID for this user. + type: integer + real_name: + description: The 'real' name for this user, if any. + type: string + nick: + description: >- + The user's nickname. Currently, this is extracted from the real_name, + name, or email field. + type: string + name: + description: The user's Bugzilla login. + type: string + email: + description: The user's email address. Currently, this is the same value as the name. + type: string diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 0000000000..9037088612 --- /dev/null +++ b/openapi/openapi.yaml @@ -0,0 +1,219 @@ +openapi: 3.1.0 +info: + title: WebService API Reference + description: > + This is the standard REST API for external programs that want to interact + with Bugzilla. It provides a REST interface to various Bugzilla functions. + license: + name: MPL-2.0 + url: https://github.com/mozilla-bteam/bmo/blob/master/LICENSE + version: 1.0.0 +servers: + - url: https://bugzilla.mozilla.org/rest + description: Production issue tracker for Firefox and other Mozilla products. + - url: https://bugzilla-dev.allizom.org/rest + description: Test instance for Bugzilla. +paths: + /bug/{bug_id}/attachment: + $ref: paths/bug_{bug_id}_attachment.yaml + /bug/attachment/{attachment_id}: + $ref: paths/bug_attachment_{attachment_id}.yaml + /bug/{id_or_alias}: + $ref: paths/bug_{id_or_alias}.yaml + /bug/{id}/history: + $ref: paths/bug_{id}_history.yaml + /bug: + $ref: paths/bug.yaml + /bug/{bug_id}/graph: + $ref: paths/bug_{bug_id}_graph.yaml + /bug/possible_duplicates: + $ref: paths/bug_possible_duplicates.yaml + /bug/{id_or_alias}/comment: + $ref: paths/bug_{id_or_alias}_comment.yaml + /bug/comment/{comment_id}: + $ref: paths/bug_comment_{comment_id}.yaml + /bug/{id}/comment: + $ref: paths/bug_{id}_comment.yaml + /bug/comment/tags/{query}: + $ref: paths/bug_comment_tags_{query}.yaml + /bug/comment/{comment_id}/tags: + $ref: paths/bug_comment_{comment_id}_tags.yaml + /bug/comment/render: + $ref: paths/bug_comment_render.yaml +components: + securitySchemes: + X-BUGZILLA-API-KEY: + type: apiKey + description: > + You can specify 'X-BUGZILLA-API-KEY' header with the API key as a value + to any request, and you will be authenticated as that user if the key is + correct and has not been revoked. + + + You can set up an API key by using the [API Keys + tab](https://bmo.readthedocs.io/en/latest/using/preferences.html#api-keys) + in the Preferences pages. + in: header + name: X-BUGZILLA-API-KEY + Bugzilla_api_key: + type: apiKey + description: > + You can specify an API key via the `Bugzilla_api_key` query parameter, + and you will be authenticated as that user if the key is correct and has + not been revoked. + + + > [!WARNING] + + It should be noted that this authentication method is not recommended + for use and it is likely to be deprecated in future versions of BMO, due + to security concerns. + in: query + name: Bugzilla_api_key + api_key: + type: apiKey + description: > + You can specify an API key via the `api_key` query parameter, and you + will be authenticated as that user if the key is correct and has not + been revoked. + + + > [!WARNING] + + It should be noted that this authentication method is not recommended + for use and it is likely to be deprecated in future versions of BMO, due + to security concerns. + in: query + name: api_key +tags: + - name: Attachments + description: >- + The Bugzilla API for creating, changing, and getting the details of + attachments. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/attachment.html + - name: Bugs + description: >- + This part of the Bugzilla REST API allows you to file new bugs in Bugzilla + and to get information about existing bugs. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/bug.html + - name: Bug User Last Visited + description: Update the last-visited time for the specified bug and current user. + externalDocs: + url: >- + https://bmo.readthedocs.io/en/latest/api/core/v1/bug-user-last-visit.html + - name: Bugzilla Information + description: >- + These methods are used to get general configuration information about this + Bugzilla instance. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/bugzilla.html + - name: Classifications + description: >- + This part of the Bugzilla API allows you to deal with the available + classifications. You will be able to get information about them as well as + manipulate them. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/classification.html + - name: Comments + description: This allows you to get data about comments, given a bug ID or comment ID. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/comment.html + - name: Components + description: >- + This part of the Bugzilla API looks at individual components and also + allows updating their information. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/component.html + - name: Bug Fields + description: The Bugzilla API for getting details about bug fields. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/field.html + - name: Flag Activity + description: >- + This API provides information about activity relating to bug and + attachment flags. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/flag-activity.html + - name: General + description: >- + This is the standard REST API for external programs that want to interact + with Bugzilla. It provides a REST interface to various Bugzilla functions. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/general.html + - name: Github + description: > + This API endpoint is for creating attachments in a bug that are redirect + links to a + + specific Github pull request. This allows a bug viewer to click on the + Github link + + and be automatically redirected to the pull request. + + + **Github Setup Instructions** + + + * From the repository main page, click on the Settings tab. + + * Click on Webhooks from the left side menu. + + * Click on the Add Webhook button near the top right. + + * For the payload url, enter + ``https://bugzilla.mozilla.org/rest/github/pull_request``. + + * Choose ``application/json`` for the content type. + + * You will need to enter the signature secret obtained from a BMO admin + (DO NOT SHARE). + + * Make sure Enable SSL is turned on. + + * Select "Let me select individual events" and only enable changes for + "Pull Requests". + + * Make sure at the bottom that "Active" is checked on. + + * Save the webhook. + + + > **Note:** + Past pull requests will not automatically get a link created in the bug. New pull + requests should get the link automatically when the pull request is first created. + + > **Note:** + The API endpoint looks at the pull request title for the bug id so + make sure the title is formatted correctly to allow the bug id to be determined. + Examples are: ``Bug 1234:``, ``Bug - 1234``, ``bug 1234``, or ``Bug 1234 -``. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/github.html + - name: Groups + description: The API for creating, changing, and getting information about groups. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/group.html + - name: Products + description: >- + This part of the Bugzilla API allows you to list the available products + and get information about them. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/product.html + - name: Users + description: >- + This part of the Bugzilla API allows you to create user accounts, get + information about user accounts and to log in or out using an existing + account. + externalDocs: + url: https://bmo.readthedocs.io/en/latest/api/core/v1/user.html + - name: Webhooks + description: >- + These methods are used to access information about and update your + configured webhooks. + externalDocs: + url: >- + https://bmo.readthedocs.io/en/latest/extensions/Webhooks/api/v1/webhooks.html#list +externalDocs: + description: Sphinx WebService API Reference + url: https://bugzilla.readthedocs.io/en/latest/api/ diff --git a/openapi/paths/bug.yaml b/openapi/paths/bug.yaml new file mode 100644 index 0000000000..aab062e18e --- /dev/null +++ b/openapi/paths/bug.yaml @@ -0,0 +1,458 @@ +get: + summary: Search for bugs based on particular criteria + description: > + Allows you to search for bugs based on specific criteria. Bugs are returned + if they match the criteria specified. Criteria are joined in a logical AND, + meaning bugs returned must match all of the specified criteria. + parameters: + - name: alias + in: query + description: >- + The unique alias of this bug. A null value will be returned if this bug + has no alias. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: assigned_to + in: query + description: The login name of a user that a bug is assigned to. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: component + in: query + description: >- + The name of the Component that the bug is in. Note that if there are + multiple Components with the same name, and you search for that name, + bugs in *all* those Components will be returned. If you don't want this, + be sure to also specify the ``product`` argument. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: count_only + in: query + description: >- + If set to true, an object with a single key called "bug_count" will be + returned, which is the number of bugs that matched the search. + schema: + oneOf: + - type: boolean + - type: array + items: + type: boolean + - name: creation_time + in: query + description: >- + Searches for bugs that were created at this time or later. May not be an + array. + schema: + type: string + format: date-time + - name: creator + in: query + description: The login name of the user who created the bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: reporter + in: query + description: >- + The name of the user who reported the bug, for backwards compatibility + with older Bugzillas. + schema: + oneOf: + - type: string + - type: array + items: + type: string + deprecated: true + - name: description + in: query + description: The description (initial comment) of the bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: filed_via + in: query + description: Searches for bugs that were created with this method. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: id + in: query + description: The numeric ID of the bug. + schema: + oneOf: + - type: integer + - type: array + items: + type: integer + - name: last_change_time + in: query + description: >- + Searches for bugs that were modified at this time or later. May not be + an array. + schema: + type: string + format: date-time + - name: limit + in: query + description: >- + Limit the number of results returned. If the value is unset, zero or + greater than the maximum value set by the administrator, which is 10,000 + by default, then the maximum value will be used instead. This is a + preventive measure against DoS-like attacks on Bugzilla. Use the + ``offset`` argument described below to retrieve more results. + schema: + type: integer + - name: longdescs.count + in: query + description: >- + The number of comments a bug has. The bug's description is the first + comment. For example, to find bugs which someone has commented on after + they have been filed, search on ``longdescs.count`` *greater than* 1. + schema: + type: integer + - name: offset + in: query + description: >- + Used in conjunction with the ``limit`` argument, ``offset`` defines the + starting position for the search. For example, given a search that would + return 100 bugs, setting ``limit`` to 10 and ``offset`` to 10 would + return bugs 11 through 20 from the set of 100. + schema: + type: integer + - name: op_sys + in: query + description: The "Operating System" field of a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: platform + in: query + description: The Platform (sometimes called "Hardware") field of a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: priority + in: query + description: The Priority field on a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: product + in: query + description: The name of the Product that the bug is in. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: quicksearch + in: query + description: Search for bugs using quicksearch syntax. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: resolution + in: query + description: >- + The current resolution--only set if a bug is closed. You can find open + bugs by searching for bugs with an empty resolution. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: severity + in: query + description: The Severity field on a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: status + in: query + description: >- + The current status of a bug (not including its resolution, if it has + one, which is a separate field above). + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: summary + in: query + description: >- + Searches for substrings in the single-line Summary field on bugs. If you + specify an array, then bugs whose summaries match *any* of the passed + substrings will be returned. Note that unlike searching in the Bugzilla + UI, substrings are not split on spaces. So searching for ``foo bar`` + will match "This is a foo bar" but not "This foo is a bar". ``['foo', + 'bar']``, would, however, match the second item. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: tags + in: query + description: >- + Searches for a bug with the specified tag. If you specify an array, then + any bugs that match *any* of the tags will be returned. Note that tags + are personal to the currently logged in user. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: target_milestone + in: query + description: >- + The Target Milestone field of a bug. Note that even if this Bugzilla + does not have the Target Milestone field enabled, you can still search + for bugs by Target Milestone. However, it is likely that in tha case, + most bugs will not have a Target Milestone set (it defaults to "---" + when the field isn't enabled). + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: qa_contact + in: query + description: >- + he login name of the bug's QA Contact. Note that even if this Bugzilla + does not have the QA Contact field enabled, you can still search for + bugs by QA Contact (though it is likely that no bug will have a QA + Contact set, if the field is disabled). + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: triage_owner + in: query + description: The login name of the Triage Owner of a bug's component. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: type + in: query + description: The Type field on a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: url + in: query + description: The "URL" field of a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: version + in: query + description: The Version field of a bug. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - name: whiteboard + in: query + description: >- + Search the "Status Whiteboard" field on bugs for a substring. Works the + same as the ``summary`` field described above, but searches the Status + Whiteboard field. + schema: + oneOf: + - type: string + - type: array + items: + type: string + responses: + '200': + description: A list of bugs matching the search criteria + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: ../components/schemas/Bug.yaml + example: + bugs: + - id: 35 + alias: null + assigned_to: user@bugzilla.org + component: Widgets + creation_time: '2014-09-23T19:12:17Z' + creator: user@bugzilla.org + description: Bug description goes here. + filed_via: REST API + last_change_time: '2014-09-28T21:03:47Z' + op_sys: All + platform: All + priority: P1 + product: MyProduct + resolution: null + severity: critical + status: NEW + summary: Bug summary goes here. + tags: null + target_milestone: '---' + qa_contact: null + triage_owner: null + type: defect + url: null + version: null + whiteboard: null + longdescs_count: 2 + default: + description: > + If you specify an invalid value for a particular field, you just won’t + get any results for that value. + + + * 1000 (Parameters Required) + You may not search without any search terms. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bugs +post: + summary: Create a new bug + description: > + This endpoint allows you to create a new bug in Bugzilla. If you specify any + invalid fields, an error will be thrown stating which field is invalid. If + you specify any fields you are not allowed to set, they will just be set to + their defaults or ignored. + + + You cannot currently set all the items here that you can set on + enter_bug.cgi. + + + The WebService interface may allow you to set things other than those listed + here, but realize that anything undocumented here may likely change in the + future. + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/NewBug.yaml + example: + product: TestProduct + component: TestComponent + version: unspecified + summary: This is a test bug - please disregard + alias: SomeAlias + op_sys: All + priority: P1 + platform: All + type: defect + responses: + '200': + description: A successful bug creation response + content: + application/json: + schema: + type: object + properties: + id: + description: This is the ID of the newly-filed bug. + type: integer + example: + id: 12345 + default: + description: | + Various error responses, including: + + * 51 (Invalid Object) + You specified a field value that is invalid. The error message will have more details. + * 103 (Invalid Alias) + The alias you specified is invalid for some reason. See the error message for more details. + * 104 (Invalid Field) + One of the drop-down fields has an invalid value, or a value entered in a text field is too long. The error message will have more detail. + * 105 (Invalid Component) + You didn't specify a component. + * 106 (Invalid Product) + Either you didn't specify a product, this product doesn't exist, or you don't have permission to enter bugs in this product. + * 107 (Invalid Summary) + You didn't specify a summary for the bug. + * 116 (Dependency Loop) + You specified values in the "blocks" and "depends_on" fields, or the "regressions" and "regressed_by" fields, that would cause a circular dependency between bugs. + * 120 (Group Restriction Denied) + You tried to restrict the bug to a group which does not exist, or which you cannot use with this product. + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 135 (Bug Type Required) + You didn't specify a type for the bug. + * 504 (Invalid User) + Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bugs diff --git a/openapi/paths/bug_attachment_{attachment_id}.yaml b/openapi/paths/bug_attachment_{attachment_id}.yaml new file mode 100644 index 0000000000..dd31bf75d7 --- /dev/null +++ b/openapi/paths/bug_attachment_{attachment_id}.yaml @@ -0,0 +1,215 @@ +get: + summary: Get a specific attachment + description: This allows you to get a specific attachment based on the attachment ID. + parameters: + - name: attachment_id + in: path + description: Integer attachment ID. + required: true + schema: + type: integer + responses: + '200': + description: A single Attachment + content: + application/json: + schema: + type: object + properties: + bugs: + type: object + const: {} + attachments: + description: > + This is an object where the attachment ids point directly to + objects describing the individual attachment. + type: object + additionalProperties: + $ref: ../components/schemas/Attachment.yaml + example: + bugs: {} + attachments: + '234': (attachment) + default: + description: > + This method can throw all the same errors as [Get + Bug](#tag/Bugs/paths/~1bug~1{bug_id}/get). In addition, it can also + throw the following error: + + + * 304 (Auth Failure, Attachment is Private) + You specified the id of a private attachment in the "attachment_ids" argument, and you are not in the "insider group" that can see private attachments. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Attachments +put: + summary: Update attachment metadata + description: This allows you to update attachment metadata in Bugzilla. + parameters: + - name: attachment_id + in: path + description: Integer attachment ID. + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: The IDs of the attachments you want to update. + type: array + items: + type: string + file_name: + description: >- + The "file name" that will be displayed in the UI for this + attachment. + type: string + summary: + description: A short string describing the attachment. + type: string + comment: + description: An optional comment to add to the attachment's bug. + type: string + content_type: + description: >- + The MIME type of the attachment, like ``text/plain`` or + ``image/png``. + type: string + is_patch: + description: >- + ``true`` if Bugzilla should treat this attachment as a patch. If + you specify this, you do not need to specify a ``content_type``. + The ``content_type`` of the attachment will be forced to + ``text/plain``. + type: boolean + is_private: + description: >- + `true` if the attachment should be private, `false` if the + attachment should be public. + type: boolean + is_obsolete: + description: '`true` if the attachment is obsolete, `false` otherwise.' + type: boolean + flags: + description: An array of Flag objects with changes to the flags. + type: array + items: + $ref: ../components/schemas/FlagUpdate.yaml + bug_flags: + description: >- + An optional array of Flag objects with changes to the flags of + the attachment's bug. + type: array + items: + $ref: ../components/schemas/FlagUpdate.yaml + required: + - ids + example: + ids: + - 2796 + summary: Test XML file + comment: Changed this from a patch to a XML file + content_type: text/xml + is_patch: 0 + responses: + '200': + description: Attachment metadata updated. + content: + application/json: + schema: + type: object + properties: + attachments: + type: array + items: + type: object + properties: + id: + description: The ID of the attachment that was updated. + type: integer + last_change_time: + description: >- + The exact time that this update was done at, for this + attachment. If no update was done (that is, no fields + had their values changed and no comment was added) then + this will instead be the last time the attachment was + updated. + type: string + format: date-time + changes: + description: >- + The changes that were actually done on this attachment. + The keys are the names of the fields that were changed, + and the values are an object with two items: + type: object + additionalProperties: + type: object + properties: + added: + description: >- + The values that were added to this field. Possibly + a comma-and-space-separated list if multiple + values were added. + type: string + removed: + description: The values that were removed from this field. + type: string + example: + attachments: + - id: 2796 + last_change_time: '2014-09-29T14:41:53Z' + changes: + content_type: + added: text/xml + removed: text/plain + is_patch: + added: '0' + removed: '1' + summary: + added: Test XML file + removed: test patch + default: + description: > + This method can throw all the same errors as [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: + + + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required + permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 132 (Flag not Unique) + The flag specified has been set multiple times. You must specify the id + value to update the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify + the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag of the "comment" to true but Markdown feature is + not enabled. + * 601 (Invalid MIME Type) + You specified a "content_type" argument that was blank, not a valid + MIME type, or not a MIME type that Bugzilla accepts for attachments. + * 603 (File Name Not Specified) + You did not specify a valid for the "file_name" argument. + * 604 (Summary Required) + You did not specify a value for the "summary" argument. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Attachments diff --git a/openapi/paths/bug_comment_render.yaml b/openapi/paths/bug_comment_render.yaml new file mode 100644 index 0000000000..dc7b9357dd --- /dev/null +++ b/openapi/paths/bug_comment_render.yaml @@ -0,0 +1,47 @@ +post: + summary: Render comment as HTML + description: Returns the HTML rendering of the provided comment text. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + text: + description: Comment text to render. + type: string + id: + description: The ID of the bug to render the comment against. + type: integer + additionalProperties: false + required: + - text + example: + id: 2345 + text: This issue has been fixed in bug 1234. + responses: + '200': + description: Text containing the HTML rendering + content: + application/json: + schema: + type: object + properties: + html: + type: string + example: + html: >- + This issue has been fixed in bug 1234. + default: + description: > + Various error responses, including those thrown by [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Comments diff --git a/openapi/paths/bug_comment_tags_{query}.yaml b/openapi/paths/bug_comment_tags_{query}.yaml new file mode 100644 index 0000000000..9fc5d04df2 --- /dev/null +++ b/openapi/paths/bug_comment_tags_{query}.yaml @@ -0,0 +1,41 @@ +get: + summary: Search for comment tags + description: Searches for tags which contain the provided substring. + parameters: + - name: query + in: path + description: Only tags containing this substring will be returned. + required: true + schema: + type: string + - name: limit + in: query + description: If provided, will return no more than `limit` tags. + schema: + type: integer + default: 10 + responses: + '200': + description: An array of matching tags + content: + application/json: + schema: + type: array + items: + type: string + example: + - spam + default: + description: > + This method can throw all of the errors that [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) throws, plus: + + + * 125 (Comment Tagging Disabled) + Comment tagging support is not available or enabled. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Comments diff --git a/openapi/paths/bug_comment_{comment_id}.yaml b/openapi/paths/bug_comment_{comment_id}.yaml new file mode 100644 index 0000000000..172ccde9f4 --- /dev/null +++ b/openapi/paths/bug_comment_{comment_id}.yaml @@ -0,0 +1,63 @@ +get: + summary: Get a specific comment + description: This allows you to get a specific comment based on the comment ID + parameters: + - name: comment_id + in: path + description: A single integer comment ID. + required: true + schema: + type: integer + responses: + '200': + description: A single Comment + content: + application/json: + schema: + type: object + properties: + comments: + description: >- + This is an object, where the keys are the numeric IDs of the + bugs, and the value is a object with a single key, comments, + which is an array of comments. + type: object + additionalProperties: + $ref: ../components/schemas/Comment.yaml + bugs: + type: object + example: + comments: + '75': + time: '2000-07-25T13:50:04Z' + text: test bug to fix problem in removing from cc list. + bug_id: 35 + count: 0 + attachment_id: null + is_private: false + tags: [] + creator: user@bugzilla.org + creation_time: '2000-07-25T13:50:04Z' + id: 75 + bugs: {} + default: + description: > + This method can throw all the same errors as [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). In addition, it can also + throw the following errors: + + + * 110 (Comment Is Private) + You specified the id of a private comment in the "comment_ids" + argument, and you are not in the "insider group" that can see + private comments. + * 111 (Invalid Comment ID) + You specified an id in the "comment_ids" argument that is invalid--either + you specified something that wasn't a number, or there is no comment with + that id. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Comments diff --git a/openapi/paths/bug_comment_{comment_id}_tags.yaml b/openapi/paths/bug_comment_{comment_id}_tags.yaml new file mode 100644 index 0000000000..18b109a2fe --- /dev/null +++ b/openapi/paths/bug_comment_{comment_id}_tags.yaml @@ -0,0 +1,67 @@ +put: + summary: Update tags for a comment + description: Adds or removes tags from a comment. + parameters: + - name: comment_id + in: path + description: The ID of the comment to update. + required: true + schema: + type: integer + example: 75 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + add: + description: The tags to attach to the comment. + type: array + items: + type: string + remove: + description: The tags to detach from the comment. + type: array + items: + type: string + additionalProperties: false + required: + - comment_id + example: + add: + - spam + - bad + responses: + '200': + description: An array of strings containing the comment's updated tags. + content: + application/json: + schema: + type: array + items: + type: string + example: + - bad + - spam + default: + description: > + This method can throw all of the errors that [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get) throws, plus: + + + * 125 (Comment Tagging Disabled) + Comment tagging support is not available or enabled. + * 126 (Invalid Comment Tag) + The comment tag provided was not valid (e.g. contains invalid characters). + * 127 (Comment Tag Too Short) + The comment tag provided is shorter than the minimum length. + * 128 (Comment Tag Too Long) + The comment tag provided is longer than the maximum length. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Comments diff --git a/openapi/paths/bug_possible_duplicates.yaml b/openapi/paths/bug_possible_duplicates.yaml new file mode 100644 index 0000000000..4cacb28805 --- /dev/null +++ b/openapi/paths/bug_possible_duplicates.yaml @@ -0,0 +1,70 @@ +get: + summary: Gets a list of possible duplicate bugs + description: > + Gets a list of possible duplicate bugs based on a given bug ID or bug + summary. + parameters: + - name: id + in: query + description: The ID of a bug to find duplicates of. + schema: + type: integer + - name: summary + in: query + description: A summary to search for duplicates of, only used if no bug ID is given. + schema: + type: string + - name: product + in: query + description: A product group to limit the search in. + schema: + type: string + - name: limit + in: query + description: > + Limit the number of results returned. If the value is unset, zero, or + greater than the maximum value set by the administrator (default: + 10,000), the maximum value will be used instead. This is a preventive + measure against DoS-like attacks on Bugzilla. + schema: + type: integer + responses: + '200': + description: A list of possible duplicate bugs + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: ../components/schemas/BugWithHistory.yaml + example: + bugs: + - id: 35 + alias: null + history: + - when: '2014-09-23T19:12:17Z' + who: user@bugzilla.org + changes: + - field_name: priority + added: P1 + removed: P2 + - field_name: severity + added: critical + removed: blocker + - when: '2014-09-28T21:03:47Z' + who: user@bugzilla.org + changes: + - field_name: flagtypes.name + added: blocker? + removed: '' + default: + description: Various error responses + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bugs diff --git a/openapi/paths/bug_{bug_id}_attachment.yaml b/openapi/paths/bug_{bug_id}_attachment.yaml new file mode 100644 index 0000000000..3cc367935a --- /dev/null +++ b/openapi/paths/bug_{bug_id}_attachment.yaml @@ -0,0 +1,188 @@ +get: + summary: Get all attachments for a bug + description: This allows you to get all current attachments for a bug. + parameters: + - name: bug_id + in: path + description: Integer bug ID. + required: true + schema: + type: integer + responses: + '200': + description: A list of Attachments + content: + application/json: + schema: + type: object + properties: + bugs: + description: > + This is an object that has integer bug IDs for keys and the + values are arrays of objects as attachments. + type: object + additionalProperties: + type: array + items: + $ref: ../components/schemas/Attachment.yaml + attachments: + type: object + const: {} + example: + bugs: + '1345': + - (attachment) + - (attachment) + attachments: {} + default: + description: >- + This method can throw all the same errors as [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Attachments +post: + summary: Create attachment on a bug + description: This allows you to add an attachment to a bug in Bugzilla. + parameters: + - $ref: '#/components/parameters/BugId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: >- + The IDs or aliases of bugs that you want to add this attachment + to. The same attachment and comment will be added to all these + bugs. + type: array + items: + type: + - string + - integer + data: + description: >- + The content of the attachment. You must encode it in base64 + using an appropriate client library such as ``MIME::Base64`` for + Perl. + type: string + format: base64 + file_name: + description: >- + The "file name" that will be displayed in the UI for this + attachment and also downloaded copies will be given. + type: string + summary: + description: A short string describing the attachment. + type: string + content_type: + description: >- + The MIME type of the attachment, like ``text/plain`` or + ``image/png``. + type: string + comment: + description: A comment to add along with this attachment. + type: string + is_patch: + description: >- + ``true`` if Bugzilla should treat this attachment as a patch. If + you specify this, you do not need to specify a ``content_type``. + The ``content_type`` of the attachment will be forced to + ``text/plain``. Defaults to ``false`` if not specified. + type: boolean + is_private: + description: >- + ``true`` if the attachment should be private (restricted to the + "insidergroup"), ``false`` if the attachment should be public. + Defaults to ``false`` if not specified. + type: boolean + flags: + description: Flags objects to add to the attachment. + type: array + items: + $ref: ../components/schemas/NewFlag.yaml + bug_flags: + description: Flag objects to add to the attachment's bug. + type: array + items: + $ref: ../components/schemas/NewFlag.yaml + required: + - ids + - data + - file_name + - summary + - content_type + example: + ids: + - 35 + is_patch: true + comment: This is a new attachment comment + summary: Test Attachment + content_type: text/plain + data: (Some base64 encoded content) + file_name: test_attachment.patch + obsoletes: [] + is_private: false + flags: + - name: review + status: '?' + requestee: user@bugzilla.org + new: true + responses: + '200': + description: Attachment IDs created. + content: + application/json: + schema: + type: object + properties: + ids: + type: array + items: + type: string + example: + ids: + - '2797' + default: + description: > + This method can throw all the same errors as [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: + + + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required + permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify + the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag of the comment to true but the Markdown feature is not enabled. + * 600 (Attachment Too Large) + You tried to attach a file that was larger than Bugzilla will accept. + * 601 (Invalid MIME Type) + You specified a "content_type" argument that was blank, not a valid + MIME type, or not a MIME type that Bugzilla accepts for attachments. + * 603 (File Name Not Specified) + You did not specify a valid for the "file_name" argument. + * 604 (Summary Required) + You did not specify a value for the "summary" argument. + * 606 (Empty Data) + You set the "data" field to an empty string. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Attachments diff --git a/openapi/paths/bug_{bug_id}_graph.yaml b/openapi/paths/bug_{bug_id}_graph.yaml new file mode 100644 index 0000000000..0ba1def01b --- /dev/null +++ b/openapi/paths/bug_{bug_id}_graph.yaml @@ -0,0 +1,141 @@ +get: + summary: Return a graph of bug relationships + description: >- + Return a graph of bug relationships such as dependencies, regressions, and + duplicates. By default, resolved bugs are not returned but can be if needed. + The bug ID provided will be the root node of the graph. + parameters: + - name: bug_id + in: path + description: The bug ID that will be the root node of the graph. + required: true + schema: + type: integer + - name: ids_only + in: query + description: Do not return simple bug data with each bug ID in the tree. + schema: + type: boolean + default: false + - name: depth + in: query + description: Limit the depth of the graph. + schema: + type: integer + default: 3 + maximum: 9 + - name: show_resolved + in: query + description: Enable if you want to also see RESOLVED bugs in the graph. + schema: + type: boolean + default: false + - name: relationship + in: query + description: >- + The default is the dependencies graph. To return the graph for other + types, pass this parameter. + schema: + type: string + default: dependencies + enum: + - dependencies + - duplicates + - regressions + responses: + '200': + description: > + A graph of bug relationships + + + The default return object will be an object with two trees based on the + type of relationship selected. For dependencies, it will be ``blocked`` + and ``dependson`` For regressions, it will be be ``regresses`` and + ``regressed_by``. And for duplicates, it will be ``dupe_of`` and + ``dupe``. + content: + application/json: + schema: + oneOf: + - type: object + title: dependencies + properties: + blocked: + $ref: ../components/schemas/BugNode.yaml + dependson: + $ref: ../components/schemas/BugNode.yaml + - type: object + title: regressions + properties: + regresses: + $ref: ../components/schemas/BugNode.yaml + regressed_by: + $ref: ../components/schemas/BugNode.yaml + - type: object + title: duplicates + properties: + dupe_of: + $ref: ../components/schemas/BugNode.yaml + dupe: + $ref: ../components/schemas/BugNode.yaml + example: + blocked: + '2': + '3': + bug: + alias: null + id: 3 + is_confirmed: 1 + op_sys: Unspecified + platform: Unspecified + priority: '--' + resolution: '' + severity: normal + status: NEW + summary: Another new test bug + target_milestone: '---' + type: defect + url: '' + version: unspecified + whiteboard: '' + bug: + alias: null + id: 2 + is_confirmed: 1 + op_sys: Unspecified + platform: Unspecified + priority: '--' + resolution: '' + severity: normal + status: NEW + summary: this is a new test bug + target_milestone: '---' + type: defect + url: '' + version: unspecified + whiteboard: '' + bug: + alias: null + id: 1 + is_confirmed: 1 + op_sys: Unspecified + platform: Unspecified + priority: '--' + resolution: '' + severity: normal + status: NEW + summary: This is a new test bug + target_milestone: '---' + type: defect + url: '' + version: unspecified + whiteboard: '' + dependson: {} + default: + description: Various error responses + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bugs diff --git a/openapi/paths/bug_{id_or_alias}.yaml b/openapi/paths/bug_{id_or_alias}.yaml new file mode 100644 index 0000000000..ed1a1ca64b --- /dev/null +++ b/openapi/paths/bug_{id_or_alias}.yaml @@ -0,0 +1,202 @@ +get: + summary: Get information about a bug + description: Gets information about a particular bug using its ID or alias. + parameters: + - $ref: ../components/parameters/BugIdOrAlias.yaml + - name: include_fields + in: query + description: > + Specify the fields to be included in the return value. + + + Custom fields are included by default, similar to normal bug fields. To + include only custom fields, use `_custom` in include_fields. Extra + fields can be retrieved by specifying `_extra` or the field name in + include_fields. + schema: + type: array + items: + type: string + responses: + '200': + description: A list of Bugs + content: + application/json: + schema: + type: object + properties: + faults: + type: array + bugs: + type: array + items: + $ref: ../components/schemas/Bug.yaml + example: + faults: [] + bugs: + - assigned_to_detail: + id: 2 + real_name: Test User + nick: user + name: user@bugzilla.org + email: user@bugzilla.org + flags: + - type_id: 11 + modification_date: '2014-09-28T21:03:47Z' + name: blocker + status: '?' + id: 2906 + setter: user@bugzilla.org + creation_date: '2014-09-28T21:03:47Z' + resolution: INVALID + id: 35 + type: defect + qa_contact: '' + triage_owner: '' + version: '1.0' + status: RESOLVED + creator: user@bugzilla.org + cf_drop_down: '---' + summary: test bug + last_change_time: '2014-09-23T19:12:17Z' + platform: All + url: '' + classification: Unclassified + cc_detail: + - id: 786 + real_name: Foo Bar + nick: foo + name: foo@bar.com + email: foo@bar.com + priority: P1 + is_confirmed: true + creation_time: '2000-07-25T13:50:04Z' + assigned_to: user@bugzilla.org + alias: null + cf_large_text: '' + groups: [] + op_sys: All + cf_bug_id: null + depends_on: [] + is_cc_accessible: true + is_open: false + cf_qa_list_4: '---' + keywords: [] + cc: + - foo@bar.com + see_also: [] + deadline: null + is_creator_accessible: true + whiteboard: '' + dupe_of: null + duplicates: [] + target_milestone: '---' + cf_mulitple_select: [] + component: SaltSprinkler + severity: critical + cf_date: null + product: FoodReplicator + creator_detail: + id: 28 + real_name: hello + nick: namachi + name: user@bugzilla.org + email: namachi@netscape.com + cf_free_text: '' + blocks: [] + regressed_by: [] + regressions: [] + comment_count: 12 + default: + description: | + Various error responses, including: + + * 100 (Invalid Bug Alias) + If you specified an alias and there is no bug with that alias. + * 101 (Invalid Bug ID) + The bug_id you specified doesn't exist in the database. + * 102 (Access Denied) + You do not have access to the bug_id you specified. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bugs +put: + summary: Update a Bug + description: > + Allows you to update the fields of a bug. Automatically sends emails out + about the changes. + parameters: + - $ref: ../components/parameters/BugIdOrAlias.yaml + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/BugUpdate.yaml + example: + ids: + - 35 + status: IN_PROGRESS + keywords: + add: + - funny + - stupid + responses: + '200': + description: A list of bugs that were updated + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: ../components/schemas/UpdatedBug.yaml + example: + bugs: + - alias: null + changes: + keywords: + added: funny, stupid + removed: '' + status: + added: IN_PROGRESS + removed: CONFIRMED + id: 35 + last_change_time: '2014-09-29T14:25:35Z' + default: + description: > + This method can throw all the same errors as [Get + Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get), plus: + + + * 129 (Flag Status Invalid) + The flag status is invalid. + * 130 (Flag Modification Denied) + You tried to request, grant, or deny a flag but only a user with the required + permissions may make the change. + * 131 (Flag not Requestable from Specific Person) + You can't ask a specific person for the flag. + * 132 (Flag not Unique) + The flag specified has been set multiple times. You must specify the id + value to update the flag. + * 133 (Flag Type not Unique) + The flag type specified matches several flag types. You must specify + the type id value to update or add a flag. + * 134 (Inactive Flag Type) + The flag type is inactive and cannot be used to create new flags. + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag of the "comment" to true but Markdown feature is + not enabled. + * 601 (Invalid MIME Type) + You specified a "content_type" argument that was blank, not a valid + MIME type, or not a MIME type that Bugzilla accepts for attachments. + * 603 (File Name Not Specified) + You did not specify a valid for the "file_name" argument. + * 604 (Summary Required) + You did not specify a value for the "summary" argument. + tags: + - Bugs diff --git a/openapi/paths/bug_{id_or_alias}_comment.yaml b/openapi/paths/bug_{id_or_alias}_comment.yaml new file mode 100644 index 0000000000..6077d0176b --- /dev/null +++ b/openapi/paths/bug_{id_or_alias}_comment.yaml @@ -0,0 +1,67 @@ +get: + summary: Get all comments for a bug + description: >- + This allows you to get all comments for a particular bug using the bug ID or + alias. + parameters: + - $ref: ../components/parameters/BugIdOrAlias.yaml + - name: new_since + in: query + description: If specified, the method will only return comments newer than this time. + schema: + type: string + format: date-time + responses: + '200': + description: A list of Comments + content: + application/json: + schema: + type: object + properties: + bugs: + description: > + This is an object, where the keys are the numeric IDs of the + bugs, and the value is a object with a single key, comments, + which is an array of comments. + type: object + additionalProperties: + type: object + properties: + comments: + type: array + items: + $ref: ../components/schemas/Comment.yaml + comments: + type: object + example: + bugs: + '35': + comments: + - time: '2000-07-25T13:50:04Z' + text: test bug to fix problem in removing from cc list. + bug_id: 35 + count: 0 + attachment_id: null + is_private: false + tags: [] + creator: user@bugzilla.org + creation_time: '2000-07-25T13:50:04Z' + id: 75 + comments: {} + default: + description: | + Various error responses, including: + + * 100 (Invalid Bug Alias) + If you specified an alias and there is no bug with that alias. + * 101 (Invalid Bug ID) + The bug_id you specified doesn't exist in the database. + * 102 (Access Denied) + You do not have access to the bug_id you specified. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Comments diff --git a/openapi/paths/bug_{id}_comment.yaml b/openapi/paths/bug_{id}_comment.yaml new file mode 100644 index 0000000000..15697b18dd --- /dev/null +++ b/openapi/paths/bug_{id}_comment.yaml @@ -0,0 +1,90 @@ +post: + summary: Create a comment on a bug + description: >- + This allows you to add a comment to a bug in Bugzilla. All comments created + via the API will be considered Markdown (specifically GitHub Flavored + Markdown). + parameters: + - $ref: ../components/parameters/BugIdOrAlias.yaml + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: List of integer bug IDs to add the comment to. + type: array + items: + type: integer + comment: + description: >- + The comment to append to the bug. If this is empty or all + whitespace, an error will be thrown saying that you did not set + the ``comment`` parameter. + type: string + is_private: + description: >- + If set to true, the comment is private, otherwise it is assumed + to be public. + type: boolean + is_markdown: + description: If true, the comment will be rendered as markdown. + type: boolean + default: false + work_time: + description: >- + Adds this many hours to the "Hours Worked" on the bug. If you + are not in the time tracking group, this value will be ignored. + type: number + additionalProperties: false + required: + - comment + example: + ids: + - 123 + - 456 + comment: This is an additional comment + is_private: false + is_markdown: true + work_time: 2.5 + responses: + '200': + description: ID of the newly-created comment + content: + application/json: + schema: + type: object + properties: + id: + type: integer + example: + id: 789 + default: + description: | + Various error responses, including: + + * 54 (Hours Worked Too Large) + You specified a "work_time" larger than the maximum allowed value of + "99999.99". + * 100 (Invalid Bug Alias) + If you specified an alias and there is no bug with that alias. + * 101 (Invalid Bug ID) + The id you specified doesn't exist in the database. + * 109 (Bug Edit Denied) + You did not have the necessary rights to edit the bug. + * 113 (Can't Make Private Comments) + You tried to add a private comment, but don't have the necessary rights. + * 114 (Comment Too Long) + You tried to add a comment longer than the maximum allowed length + (65,535 characters). + * 140 (Markdown Disabled) + You tried to set the "is_markdown" flag to true but the Markdown feature + is not enabled. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Comments diff --git a/openapi/paths/bug_{id}_history.yaml b/openapi/paths/bug_{id}_history.yaml new file mode 100644 index 0000000000..b46dde1a85 --- /dev/null +++ b/openapi/paths/bug_{id}_history.yaml @@ -0,0 +1,55 @@ +get: + summary: Get the history of changes for a specific bug + description: > + Gets the history of changes for a particular bug in the database. You can + specify a bug ID or alias and, optionally, a datetime timestamp to only show + history since that date. + parameters: + - $ref: ../components/parameters/BugIdOrAlias.yaml + - name: new_since + in: query + description: A datetime timestamp to only show history since. + schema: + type: string + format: date-time + responses: + '200': + description: A list of bugs with their history + content: + application/json: + schema: + type: object + properties: + bugs: + type: array + items: + $ref: ../components/schemas/BugWithHistory.yaml + example: + bugs: + - id: 35 + alias: null + history: + - when: '2014-09-23T19:12:17Z' + who: user@bugzilla.org + changes: + - field_name: priority + added: P1 + removed: P2 + - field_name: severity + added: critical + removed: blocker + - when: '2014-09-28T21:03:47Z' + who: user@bugzilla.org + changes: + - field_name: flagtypes.name + added: blocker? + removed: '' + default: + description: | + Same as [Get Bug](#tag/Bugs/paths/~1bug~1{id_or_alias}/get). + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bugs From a468d72c8fdfd18ed94017a59902867d1259dae1 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 29 Feb 2024 15:40:34 +0100 Subject: [PATCH 26/29] Added Operation Ids --- openapi/paths/bug.yaml | 2 ++ openapi/paths/bug_attachment_{attachment_id}.yaml | 2 ++ openapi/paths/bug_comment_render.yaml | 1 + openapi/paths/bug_comment_tags_{query}.yaml | 1 + openapi/paths/bug_comment_{comment_id}.yaml | 1 + openapi/paths/bug_comment_{comment_id}_tags.yaml | 1 + openapi/paths/bug_possible_duplicates.yaml | 1 + openapi/paths/bug_{bug_id}_attachment.yaml | 2 ++ openapi/paths/bug_{bug_id}_graph.yaml | 1 + openapi/paths/bug_{id_or_alias}.yaml | 2 ++ openapi/paths/bug_{id_or_alias}_comment.yaml | 1 + openapi/paths/bug_{id}_comment.yaml | 1 + openapi/paths/bug_{id}_history.yaml | 1 + 13 files changed, 17 insertions(+) diff --git a/openapi/paths/bug.yaml b/openapi/paths/bug.yaml index aab062e18e..d369faf5d2 100644 --- a/openapi/paths/bug.yaml +++ b/openapi/paths/bug.yaml @@ -4,6 +4,7 @@ get: Allows you to search for bugs based on specific criteria. Bugs are returned if they match the criteria specified. Criteria are joined in a logical AND, meaning bugs returned must match all of the specified criteria. + operationId: search_bugs parameters: - name: alias in: query @@ -388,6 +389,7 @@ post: The WebService interface may allow you to set things other than those listed here, but realize that anything undocumented here may likely change in the future. + operationId: create_bug requestBody: content: application/json: diff --git a/openapi/paths/bug_attachment_{attachment_id}.yaml b/openapi/paths/bug_attachment_{attachment_id}.yaml index dd31bf75d7..f5287bb685 100644 --- a/openapi/paths/bug_attachment_{attachment_id}.yaml +++ b/openapi/paths/bug_attachment_{attachment_id}.yaml @@ -1,6 +1,7 @@ get: summary: Get a specific attachment description: This allows you to get a specific attachment based on the attachment ID. + operationId: get_attachment parameters: - name: attachment_id in: path @@ -48,6 +49,7 @@ get: put: summary: Update attachment metadata description: This allows you to update attachment metadata in Bugzilla. + operationId: update_attachment parameters: - name: attachment_id in: path diff --git a/openapi/paths/bug_comment_render.yaml b/openapi/paths/bug_comment_render.yaml index dc7b9357dd..05b47302d7 100644 --- a/openapi/paths/bug_comment_render.yaml +++ b/openapi/paths/bug_comment_render.yaml @@ -1,6 +1,7 @@ post: summary: Render comment as HTML description: Returns the HTML rendering of the provided comment text. + operationId: render_comment requestBody: required: true content: diff --git a/openapi/paths/bug_comment_tags_{query}.yaml b/openapi/paths/bug_comment_tags_{query}.yaml index 9fc5d04df2..e7bfeb7159 100644 --- a/openapi/paths/bug_comment_tags_{query}.yaml +++ b/openapi/paths/bug_comment_tags_{query}.yaml @@ -1,6 +1,7 @@ get: summary: Search for comment tags description: Searches for tags which contain the provided substring. + operationId: search_comment_tags parameters: - name: query in: path diff --git a/openapi/paths/bug_comment_{comment_id}.yaml b/openapi/paths/bug_comment_{comment_id}.yaml index 172ccde9f4..419ea1fb78 100644 --- a/openapi/paths/bug_comment_{comment_id}.yaml +++ b/openapi/paths/bug_comment_{comment_id}.yaml @@ -1,6 +1,7 @@ get: summary: Get a specific comment description: This allows you to get a specific comment based on the comment ID + operationId: get_comment parameters: - name: comment_id in: path diff --git a/openapi/paths/bug_comment_{comment_id}_tags.yaml b/openapi/paths/bug_comment_{comment_id}_tags.yaml index 18b109a2fe..99b0c4a226 100644 --- a/openapi/paths/bug_comment_{comment_id}_tags.yaml +++ b/openapi/paths/bug_comment_{comment_id}_tags.yaml @@ -1,6 +1,7 @@ put: summary: Update tags for a comment description: Adds or removes tags from a comment. + operationId: update_comment_tags parameters: - name: comment_id in: path diff --git a/openapi/paths/bug_possible_duplicates.yaml b/openapi/paths/bug_possible_duplicates.yaml index 4cacb28805..c8f5862e52 100644 --- a/openapi/paths/bug_possible_duplicates.yaml +++ b/openapi/paths/bug_possible_duplicates.yaml @@ -3,6 +3,7 @@ get: description: > Gets a list of possible duplicate bugs based on a given bug ID or bug summary. + operationId: get_duplicate_bugs parameters: - name: id in: query diff --git a/openapi/paths/bug_{bug_id}_attachment.yaml b/openapi/paths/bug_{bug_id}_attachment.yaml index 3cc367935a..50afb10a64 100644 --- a/openapi/paths/bug_{bug_id}_attachment.yaml +++ b/openapi/paths/bug_{bug_id}_attachment.yaml @@ -1,6 +1,7 @@ get: summary: Get all attachments for a bug description: This allows you to get all current attachments for a bug. + operationId: get_bug_attachments parameters: - name: bug_id in: path @@ -47,6 +48,7 @@ get: post: summary: Create attachment on a bug description: This allows you to add an attachment to a bug in Bugzilla. + operationId: create_bug_attachment parameters: - $ref: '#/components/parameters/BugId' requestBody: diff --git a/openapi/paths/bug_{bug_id}_graph.yaml b/openapi/paths/bug_{bug_id}_graph.yaml index 0ba1def01b..36811aeb7f 100644 --- a/openapi/paths/bug_{bug_id}_graph.yaml +++ b/openapi/paths/bug_{bug_id}_graph.yaml @@ -4,6 +4,7 @@ get: Return a graph of bug relationships such as dependencies, regressions, and duplicates. By default, resolved bugs are not returned but can be if needed. The bug ID provided will be the root node of the graph. + operationId: bug_graph parameters: - name: bug_id in: path diff --git a/openapi/paths/bug_{id_or_alias}.yaml b/openapi/paths/bug_{id_or_alias}.yaml index ed1a1ca64b..dcd36ef366 100644 --- a/openapi/paths/bug_{id_or_alias}.yaml +++ b/openapi/paths/bug_{id_or_alias}.yaml @@ -1,6 +1,7 @@ get: summary: Get information about a bug description: Gets information about a particular bug using its ID or alias. + operationId: get_bug parameters: - $ref: ../components/parameters/BugIdOrAlias.yaml - name: include_fields @@ -128,6 +129,7 @@ put: description: > Allows you to update the fields of a bug. Automatically sends emails out about the changes. + operationId: update_bug parameters: - $ref: ../components/parameters/BugIdOrAlias.yaml requestBody: diff --git a/openapi/paths/bug_{id_or_alias}_comment.yaml b/openapi/paths/bug_{id_or_alias}_comment.yaml index 6077d0176b..8ccaf26252 100644 --- a/openapi/paths/bug_{id_or_alias}_comment.yaml +++ b/openapi/paths/bug_{id_or_alias}_comment.yaml @@ -3,6 +3,7 @@ get: description: >- This allows you to get all comments for a particular bug using the bug ID or alias. + operationId: get_bug_comments parameters: - $ref: ../components/parameters/BugIdOrAlias.yaml - name: new_since diff --git a/openapi/paths/bug_{id}_comment.yaml b/openapi/paths/bug_{id}_comment.yaml index 15697b18dd..c2399529d8 100644 --- a/openapi/paths/bug_{id}_comment.yaml +++ b/openapi/paths/bug_{id}_comment.yaml @@ -4,6 +4,7 @@ post: This allows you to add a comment to a bug in Bugzilla. All comments created via the API will be considered Markdown (specifically GitHub Flavored Markdown). + operationId: create_bug_comment parameters: - $ref: ../components/parameters/BugIdOrAlias.yaml requestBody: diff --git a/openapi/paths/bug_{id}_history.yaml b/openapi/paths/bug_{id}_history.yaml index b46dde1a85..f1f82fdd82 100644 --- a/openapi/paths/bug_{id}_history.yaml +++ b/openapi/paths/bug_{id}_history.yaml @@ -4,6 +4,7 @@ get: Gets the history of changes for a particular bug in the database. You can specify a bug ID or alias and, optionally, a datetime timestamp to only show history since that date. + operationId: get_bug_history parameters: - $ref: ../components/parameters/BugIdOrAlias.yaml - name: new_since From 5bbab24cc9a7461caa3ff19729518107e770f16b Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 29 Feb 2024 16:14:09 +0100 Subject: [PATCH 27/29] Added basic GH action for linting OpenAPI spec --- .github/actions/redocly-bundle/action.yaml | 22 ++++++++++++++++++ .github/workflows/openapi.yml | 27 ++++++++++++++++++++++ .neoconf.json | 11 +++++++++ 3 files changed, 60 insertions(+) create mode 100644 .github/actions/redocly-bundle/action.yaml create mode 100644 .github/workflows/openapi.yml create mode 100644 .neoconf.json diff --git a/.github/actions/redocly-bundle/action.yaml b/.github/actions/redocly-bundle/action.yaml new file mode 100644 index 0000000000..7341fbb748 --- /dev/null +++ b/.github/actions/redocly-bundle/action.yaml @@ -0,0 +1,22 @@ +name: redocly bundle +description: "Bundle a multi-file API description to a single file." +inputs: + apis: + description: "List of API description root filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file." + required: true + output: + description: "Name or folder for the bundle file. If you don't specify the file extension, `.yaml` is used by default. If the specified folder doesn't exist, it's created automatically. If the file specified as the bundler's output already exists, it's overwritten." + +runs: + using: "composite" + steps: + - uses: actions/setup-node@main + with: + node-version: 20 + - name: install redocly + shell: bash + run: npm install @redocly/cli -g + - name: bundle openapi spec + shell: bash + run: | + redocly bundle ${{ inputs.apis }} ${{ inputs.output && '--output' }} ${{ inputs.output }} diff --git a/.github/workflows/openapi.yml b/.github/workflows/openapi.yml new file mode 100644 index 0000000000..4c01e812fa --- /dev/null +++ b/.github/workflows/openapi.yml @@ -0,0 +1,27 @@ +name: BMO OpenAPI spec + +on: + push: + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + sparse-checkout: | + .github + openapi + + - name: bundle OpenAPI spec + uses: ./.github/actions/redocly-bundle + with: + apis: openapi/openapi.yaml + output: openapi/bundled.yaml + + - name: install vacuum + run: npm i -g @quobix/vacuum + + - name: run vacuum lint + run: vacuum lint openapi/bundled.yaml diff --git a/.neoconf.json b/.neoconf.json new file mode 100644 index 0000000000..366a73f571 --- /dev/null +++ b/.neoconf.json @@ -0,0 +1,11 @@ +{ + "lspconfig": { + "yamlls": { + "yaml": { + "schemas": { + "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml", + } + } + } + } +} From 1431ecf4b0bb832ef357d4d0add9e21bdafe7b72 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 29 Feb 2024 17:06:28 +0100 Subject: [PATCH 28/29] Basic test generation of python Client --- .github/workflows/openapi.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/.github/workflows/openapi.yml b/.github/workflows/openapi.yml index 4c01e812fa..2ab6b97df0 100644 --- a/.github/workflows/openapi.yml +++ b/.github/workflows/openapi.yml @@ -25,3 +25,23 @@ jobs: - name: run vacuum lint run: vacuum lint openapi/bundled.yaml + + test: + name: Test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: bundle OpenAPI spec + uses: ./.github/actions/redocly-bundle + with: + apis: openapi/openapi.yaml + output: openapi/bundled.yaml + + - name: Generate Python Client + uses: openapi-generators/openapitools-generator-action@v1.5.0 + with: + generator: python + openapi-file: openapi/bundled.yaml + command-args: --skip-validate-spec + # config-file: python-generator-config.yml From 653655d446eb52b3dd8058b0e78c8cbc67cc7495 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Thu, 29 Feb 2024 17:09:45 +0100 Subject: [PATCH 29/29] Made ref file relative --- openapi/components/schemas/Bug.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/components/schemas/Bug.yaml b/openapi/components/schemas/Bug.yaml index 6d0438398e..510294e117 100644 --- a/openapi/components/schemas/Bug.yaml +++ b/openapi/components/schemas/Bug.yaml @@ -283,7 +283,7 @@ properties: This field its only returned by specifying `_extra` or the field name in the `include_fields` parameter. type: array items: - $ref: '#/components/schemas/History' + $ref: ./BugHistory.yaml tags: description: > Each array item is a tag name. Note that tags are personal to the