Draft: OpenAPI V3: Endpoint to create note on MergeRequest

• Please check this box if this contribution uses AI-generated content (including content generated by GitLab Duo features) as outlined in the GitLab DCO & CLA. As a benefit of being a GitLab Community Contributor, you receive complimentary access to GitLab Duo.

What does this MR do and why?

OpenAPI: Endpoint to create note on MergeRequest

Main changes

This commit adds a missing operation to the OpenAPI V3 document: POST /projects/{id}/merge_requests/{merge_request_iid}/notes.

This operation is already described in the Markdown documentation of the API, referenced via the externalDocs link: https://docs.gitlab.com/api/notes/#create-new-merge-request-note

Important points / remaining questions

• operationId I followed the pattern of other operations to guess the value: postApiV4ProjectsIdMergeRequestsMergeRequestIidNotes Is there a specific rule that should be applied?

• body parameter: body or query destination? The documentation mentions it as a query parameter, but I noticed it also works as a body parameter. In this commit, I assumed it should be included in the requestBody.

• Optional parameters: created_at, internal, and merge_request_diff_head_sha The documentation does not specify their destination, but I tested the operation manually, and confirmed they are query parameters.

• Responses By testing the API, I observed at least 4 different status codes, which are only briefly documented in this OpenAPI definition. I’m quite sure we can provide more details, especially for the 201 response. Is there a specific API_Entity_* schema that can be created or reused?

Use case bonus with this commit

When combined with the Bump.sh CLI and GitLab script, this endpoint can be used to post a note on a given merge request whenever there is a structural change in the OpenAPI definition.

For example, in this Merge Request on my personal project, a message was automatically generated via the Bump.sh API to summarize the structural change in the OpenAPI definition: Polo2/gitlab-openapi!2 (comment 2709502157)

Added: POST /projects/{id}/merge_requests/{merge_request_iid}/notes

(yes, it’s meta 🤯)

References

Screenshots or screen recordings

How to set up and validate locally

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.