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..2ab6b97df0 --- /dev/null +++ b/.github/workflows/openapi.yml @@ -0,0 +1,47 @@ +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 + + 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 diff --git a/.neoconf.json b/.neoconf.json new file mode 100644 index 0000000000..5b8a18c93f --- /dev/null +++ b/.neoconf.json @@ -0,0 +1,14 @@ +{ + "lspconfig": { + "yamlls": { + "yaml": { + "schemas": { + "https://github.com/OAI/OpenAPI-Specification/raw/main/schemas/v3.1/schema.json#/$defs/path-item": "openapi/paths/*.yaml", + "https://github.com/OAI/OpenAPI-Specification/raw/main/schemas/v3.1/schema.json#/$defs/parameter": "openapi/components/parameters/*.yaml", + "https://github.com/OAI/OpenAPI-Specification/raw/main/schemas/v3.1/schema.json#/$defs/schema": "openapi/components/schema/*.yaml", + "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml", + } + } + } + } +} diff --git a/openapi/.gitignore b/openapi/.gitignore new file mode 100644 index 0000000000..75c2715cb1 --- /dev/null +++ b/openapi/.gitignore @@ -0,0 +1 @@ +bundled.yaml diff --git a/openapi/components/parameters/BugId.yaml b/openapi/components/parameters/BugId.yaml new file mode 100644 index 0000000000..51bf732e32 --- /dev/null +++ b/openapi/components/parameters/BugId.yaml @@ -0,0 +1,9 @@ +name: id +in: query +description: The numeric ID of the bug. +schema: + oneOf: + - type: integer + - type: array + items: + type: integer 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..510294e117 --- /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: ./BugHistory.yaml + 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/docs/general.md b/openapi/docs/general.md new file mode 100644 index 0000000000..6ddef66701 --- /dev/null +++ b/openapi/docs/general.md @@ -0,0 +1,270 @@ +# General + +This is the standard REST API for external programs that want to +interact with Bugzilla. It provides a REST interface to various Bugzilla +functions. + +## Basic Information + +**Data Format** + +The REST API only supports JSON input, and either JSON or JSONP output. +So objects sent and received must be in JSON format. + +If you need JSONP output, you must set the +`Accept: application/javascript` HTTP header and add a `callback` +parameter to name your callback. + +Parameters may also be passed in as part of the query string for non-GET +requests and will override any matching parameters in the request body. + +Example request which returns the current version of Bugzilla: + +``` http +GET /rest/version HTTP/1.1 +Host: bugzilla.example.com +``` + +Example response: + +``` http +HTTP/1.1 200 OK +Vary: Accept +Content-Type: application/json + +{ + "version" : "4.2.9+" +} +``` + +**Errors** + +When an error occurs over REST, an object is returned with the key +`error` set to `true`. + +The error contents look similar to: + +``` js +{ + "error": true, + "message": "Some message here", + "code": 123 +} +``` + +To protect the application from large requests, Bugzilla returns a 302 +redirect to the homepage when your query string is too long. The current +limit is 10 KB, which can accept roughly 1,000 bug IDs in the `id` +parameter for the `/rest/bug` method, but it could be smaller or may +lead to a 414 URI Too Long HTTP error depending on the server +configuration. Split your query into multiple requests if you encounter +the issue. + +## Common Data Types + +The Bugzilla API uses the following various types of parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
typedescription
intInteger.
doubleA floating-point number.
stringA string.

email

A string representing an email address. This value, when +returned, may be filtered based on if the user is logged in or +not.

dateA specific date. Example format: YYYY-MM-DD.

datetime

A date/time. Timezone should be in UTC unless otherwise noted. +Example format: YYYY-MM-DDTHH24:MI:SSZ.

booleantrue or false.

base64

A base64-encoded string. This is the only way to transfer binary +data via the API.

array

An array. There may be mixed types in an array. [ +and ] are used to represent the beginning and end of +arrays.

object

A mapping of keys to values. Called a "hash", "dict", or "map" in +some other programming languages. The keys are strings, and the values +can be any type. { and } are used to represent +the beginning and end of objects.

+ +Parameters that are required will be displayed in **bold** in the +parameters table for each API method. + +## Authentication + +Some methods do not require you to log in. An example of this is +`rest_single_bug`. However, authenticating yourself allows you to see +non-public information, for example, a bug that is not publicly visible. + +To authenticate yourself, you will need to use API keys: + +**API Keys** + +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 ` in the +Preferences pages. + +**WARNING**: It should be noted that additional authentication methods +exist, but they are **not recommended** for use and are likely to be +deprecated in future versions of BMO, due to security concerns. These +additional methods include the following: + +> - api key via `Bugzilla_api_key` or simply `api_key` in query +> parameters. + +## Useful Parameters + +Many calls take common arguments. These are documented below and linked +from the individual calls where these parameters are used. + +**Including Fields** + +Many calls return an array of objects with various fields in the +objects. (For example, `rest_single_bug` returns a list of `bugs` that +have fields like `id`, `summary`, `creation_time`, etc.) + +These parameters allow you to limit what fields are present in the +objects, to improve performance or save some bandwidth. + +`include_fields`: The (case-sensitive) names of fields in the response +data. Only the fields specified in the object will be returned, the rest +will not be included. Fields should be comma delimited. + +Invalid field names are ignored. + +Example request to `rest_user_get`: + +``` text +GET /rest/user/1?include_fields=id,name +``` + +would return something like: + +``` js +{ + "users" : [ + { + "id" : 1, + "name" : "user@domain.com" + } + ] +} +``` + +**Excluding Fields** + +`exclude_fields`: The (case-sensitive) names of fields in the return +value. The fields specified will not be included in the returned +objects. Fields should be comma delimited. + +Invalid field names are ignored. + +Specifying fields here overrides `include_fields`, so if you specify a +field in both, it will be excluded, not included. + +Example request to `rest_user_get`: + +``` js +GET /rest/user/1?exclude_fields=name +``` + +would return something like: + +``` js +{ + "users" : [ + { + "id" : 1, + "real_name" : "John Smith" + } + ] +} +``` + +Some calls support specifying "subfields". If a call states that it +supports "subfield" restrictions, you can restrict what information is +returned within the first field. For example, if you call +`rest_product_get` with an `include_fields` of `components.name`, then +only the component name would be returned (and nothing else). You can +include the main field, and exclude a subfield. + +There are several shortcut identifiers to ask for only certain groups of +fields to be returned or excluded: + + + + + + + + + + + + + + + + + + + + + + + + + + +
valuedescription

_all

All possible fields are returned if this is specified in +include_fields.

_default

Default fields are returned if include_fields is +empty or this is specified. This is useful if you want the default +fields in addition to a field that is not normally returned.

_extra

Extra fields are not returned by default and need to be manually +specified in include_fields either by exact field name, or +adding _extra.

+

_custom

+

Custom fields are normally returned by default unless this is +added to exclude_fields. Also you can use it in +include_fields if for example you want specific field names +plus all custom fields. Custom fields are normally only relevant to bug +objects.

diff --git a/openapi/docs/users.md b/openapi/docs/users.md new file mode 100644 index 0000000000..99c6b12dfc --- /dev/null +++ b/openapi/docs/users.md @@ -0,0 +1,2 @@ +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. diff --git a/openapi/generate_docs.sh b/openapi/generate_docs.sh new file mode 100755 index 0000000000..d492fc2ed7 --- /dev/null +++ b/openapi/generate_docs.sh @@ -0,0 +1,24 @@ +#!/bin/bash + +# Set the source and destination directories +src_dir="../docs/en/rst/api/core/v1" +dest_dir="./docs" + +# Ensure the destination directory exists +mkdir -p "$dest_dir" + +# Find all RST files recursively in the source directory +find "$src_dir" -type f -name "*.rst" -print0 | while IFS= read -r -d $'\0' rst_file; do + # Create the corresponding directory structure in the destination directory + rel_path="${rst_file#$src_dir}" + dest_file="$dest_dir${rel_path%.rst}.md" + dest_path=$(dirname "$dest_file") + mkdir -p "$dest_path" + + # Convert RST to Markdown using Pandoc + pandoc "$rst_file" -o "$dest_file" + + echo "Converted: $rst_file to $dest_file" +done + +echo "Conversion complete!" diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 0000000000..0e59a0f976 --- /dev/null +++ b/openapi/openapi.yaml @@ -0,0 +1,216 @@ +openapi: 3.1.0 +info: + title: WebService API Reference + description: + $ref: docs/general.md + 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_or_alias}/history: + $ref: paths/bug_{id_or_alias}_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/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 + /rest/bug_user_last_visit/{id}: + $ref: paths/bug_user_last_visit_{id}.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: + $ref: docs/users.md + 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/openapitools.json b/openapi/openapitools.json new file mode 100644 index 0000000000..e73b975830 --- /dev/null +++ b/openapi/openapitools.json @@ -0,0 +1,7 @@ +{ + "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json", + "spaces": 2, + "generator-cli": { + "version": "7.2.0" + } +} diff --git a/openapi/paths/bug.yaml b/openapi/paths/bug.yaml new file mode 100644 index 0000000000..d369faf5d2 --- /dev/null +++ b/openapi/paths/bug.yaml @@ -0,0 +1,460 @@ +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. + operationId: search_bugs + 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. + operationId: create_bug + 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..f5287bb685 --- /dev/null +++ b/openapi/paths/bug_attachment_{attachment_id}.yaml @@ -0,0 +1,217 @@ +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 + 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. + operationId: update_attachment + 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..05b47302d7 --- /dev/null +++ b/openapi/paths/bug_comment_render.yaml @@ -0,0 +1,48 @@ +post: + summary: Render comment as HTML + description: Returns the HTML rendering of the provided comment text. + operationId: render_comment + 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..e7bfeb7159 --- /dev/null +++ b/openapi/paths/bug_comment_tags_{query}.yaml @@ -0,0 +1,42 @@ +get: + summary: Search for comment tags + description: Searches for tags which contain the provided substring. + operationId: search_comment_tags + 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..419ea1fb78 --- /dev/null +++ b/openapi/paths/bug_comment_{comment_id}.yaml @@ -0,0 +1,64 @@ +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 + 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..fe15d53857 --- /dev/null +++ b/openapi/paths/bug_comment_{comment_id}_tags.yaml @@ -0,0 +1,72 @@ +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 + 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: + comment_id: + description: The ID of the comment to update. + type: integer + required: true + 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..c8f5862e52 --- /dev/null +++ b/openapi/paths/bug_possible_duplicates.yaml @@ -0,0 +1,71 @@ +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. + operationId: get_duplicate_bugs + 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_user_last_visit_{id}.yaml b/openapi/paths/bug_user_last_visit_{id}.yaml new file mode 100644 index 0000000000..8cc0d24a03 --- /dev/null +++ b/openapi/paths/bug_user_last_visit_{id}.yaml @@ -0,0 +1,99 @@ +get: + summary: Get last visited timestamp for bug(s) + description: Retrieves the last-visited timestamp for the specified bug(s). + operationId: get_last_visited + parameters: + - name: id + in: path + description: An integer bug ID. + required: false + schema: + type: integer + - name: ids + in: query + description: One or more optional bug IDs to get. + required: false + schema: + type: array + items: + type: integer + responses: + "200": + description: Last visited timestamps retrieved successfully. + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + description: The bug ID. + type: integer + last_visit_ts: + description: The timestamp the user last visited the bug. + type: string + format: date-time + default: + description: > + This method can throw any errors related to accessing the database or + handling the request. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bug User Last Visited +post: + summary: Update last visited time for bug(s) + description: Updates the last-visited time for the specified bug(s) and current user. + operationId: update_last_visited + parameters: + - name: id + in: path + # QUESTION: Is this required? If not this should probably be a query parameter. + required: true + description: An integer bug ID. + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ids: + description: One or more bug IDs to update. + type: array + items: + type: integer + responses: + "200": + description: Last visited time updated successfully. + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + description: The bug ID. + type: integer + last_visit_ts: + description: The timestamp the user last visited the bug. + type: string + format: date-time + default: + description: > + This method can throw the following error: + + * 1300 (User Not Involved with Bug) + The caller's account is not involved with the bug ID provided. + content: + application/json: + schema: + $ref: ../components/schemas/Error.yaml + tags: + - Bug User Last Visited diff --git a/openapi/paths/bug_{bug_id}_attachment.yaml b/openapi/paths/bug_{bug_id}_attachment.yaml new file mode 100644 index 0000000000..c5686d097c --- /dev/null +++ b/openapi/paths/bug_{bug_id}_attachment.yaml @@ -0,0 +1,190 @@ +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 + 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. + operationId: create_bug_attachment + parameters: + - $ref: ../components/parameters/BugId.yaml + 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..36811aeb7f --- /dev/null +++ b/openapi/paths/bug_{bug_id}_graph.yaml @@ -0,0 +1,142 @@ +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. + operationId: bug_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..dcd36ef366 --- /dev/null +++ b/openapi/paths/bug_{id_or_alias}.yaml @@ -0,0 +1,204 @@ +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 + 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. + operationId: update_bug + 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..cde0ca1a01 --- /dev/null +++ b/openapi/paths/bug_{id_or_alias}_comment.yaml @@ -0,0 +1,159 @@ +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. + operationId: get_bug_comments + 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 +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). + operationId: create_bug_comment + 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_or_alias}_history.yaml b/openapi/paths/bug_{id_or_alias}_history.yaml new file mode 100644 index 0000000000..f1f82fdd82 --- /dev/null +++ b/openapi/paths/bug_{id_or_alias}_history.yaml @@ -0,0 +1,56 @@ +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. + operationId: get_bug_history + 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 diff --git a/openapi/query.md b/openapi/query.md new file mode 100644 index 0000000000..884c3e7131 --- /dev/null +++ b/openapi/query.md @@ -0,0 +1,376 @@ +Documentation: +```rst +.. _rest_add_attachment: + +Create Attachment +----------------- + +This allows you to add an attachment to a bug in Bugzilla. + +**Request** + +To create attachment on a current bug: + +.. code-block:: text + + POST /rest/bug/(bug_id)/attachment + +.. code-block:: js + + { + "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 + } + ] + } + + +The params to include in the POST body, as well as the returned +data format, are the same as below. The ``bug_id`` param will be +overridden as it it pulled from the URL path. + +================ ======= ====================================================== +name type description +================ ======= ====================================================== +**ids** array 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. +**data** base64 The content of the attachment. You must encode it in + base64 using an appropriate client library such as + ``MIME::Base64`` for Perl. +**file_name** string The "file name" that will be displayed in the UI for + this attachment and also downloaded copies will be + given. +**summary** string A short string describing the attachment. +**content_type** string The MIME type of the attachment, like ``text/plain`` + or ``image/png``. +comment string A comment to add along with this attachment. +is_patch boolean ``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. +is_private boolean ``true`` if the attachment should be private + (restricted to the "insidergroup"), ``false`` if the + attachment should be public. Defaults to ``false`` if + not specified. +flags array Flags objects to add to the attachment. The object + format is described in the Flag object below. +bug_flags array Flag objects to add to the attachment's bug. See the + ``flags`` param for :ref:`rest_create_bug` for the + object format. +================ ======= ====================================================== + +Flag object: + +To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must +be provided. An optional requestee can be passed if the flag type is requestable +to a specific user. + +========= ====== ============================================================== +name type description +========= ====== ============================================================== +name string The name of the flag type. +type_id int The internal flag type ID. +status string The flags new status (i.e. "?", "+", "-" or "X" to clear a + flag). +requestee string The login of the requestee if the flag type is requestable to + a specific user. +========= ====== ============================================================== + +**Response** + +.. code-block:: js + + { + "ids" : [ + "2797" + ] + } + +==== ===== ========================= +name type description +==== ===== ========================= +ids array Attachment IDs created. +==== ===== ========================= + +**Errors** + +This method can throw all the same errors as :ref:`rest_single_bug`, 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. +``` + +OpenAPI: +```yaml +put: + summary: Update attachment metadata + description: This allows you to update attachment metadata in Bugzilla. + operationId: update_attachment + 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 +``` + +Documentation: +```rst +.. _rest-bug-user-last-visit-update: + +Update Last Visited +------------------- + +Update the last-visited time for the specified bug and current user. + +**Request** + +To update the time for a single bug id: + +.. code-block:: text + + POST /rest/bug_user_last_visit/(id) + +To update one or more bug ids at once: + +.. code-block:: text + + POST /rest/bug_user_last_visit + +.. code-block:: js + + { + "ids" : [35,36,37] + } + +======= ===== ============================== +name type description +======= ===== ============================== +**id** int An integer bug id. +**ids** array One or more bug ids to update. +======= ===== ============================== + +**Response** + +.. code-block:: js + + [ + { + "id" : 100, + "last_visit_ts" : "2014-10-16T17:38:24Z" + } + ] + +An array of objects containing the items: + +============= ======== ============================================ +name type description +============= ======== ============================================ +id int The bug id. +last_visit_ts datetime The timestamp the user last visited the bug. +============= ======== ============================================ + +**Errors** + +* 1300 (User Not Involved with Bug) + The caller's account is not involved with the bug id provided. +``` + +OpenAPI: