Create an OpenAPI contribution guide

We are working on creating a complete autogenerated OpenAPI documentation. Currently, there is no contribution guide. This issue is about collecting best practices and compiling them into a contribution guide.

The guide can be added to https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html

Related conversation: &8926 (comment 1151742900)

API annotations.

This is an example of an issue description that lining out steps to be done to update the annotation of an endpoint:

For the API::Search endpoint, we have to:

1. Check the API::Search class and:
   • Check if the parameter documentation needs to be updated
   • Check if the description block needs to be updated. Ideally this should include a success entry. Specifying a model like success Entities::EntityName will work. If you want to add more details, you can use a hash like in this example.
     • If the endpoint responds with an Array, use the is_array true helper.
   • Compare the parameters and description to the markdown documentation for this endpoint
   • Optionally add a tag to the description. (example)
2. Add the endpoint to the OpenApiV2 documentation by modifying lib/api/api.rb and moving mount Search into the other namespace, next to add_open_api_documentation!
3. Run rake gitlab:openapi:generate
4. Review changes in doc/api/openapi/openapi_v2.yaml. You can check the content of the file by pasting it into https://editor.swagger.io. Errors will be shown on the left side.
5. Please do not commit the changes in doc/api/openapi/openapi_v2.yaml. Many teams will work on this in parallel. To avoid conflicts, we will try to have only one MR modifying the file at a time. @elim-ext or @Andysoiron will create a new MR with the latest updates every few days.
6. Commit the other changes and create an MR.

📺 Video guide

https://www.youtube.com/watch?v=V1hUlFOBbYY

Example MRs

• Add GroupPushRule to OpenAPI documetation (EE endpoint)
• Add API::MergeRequestDiffs to OpenApi V2

Edge cases

Edge cases are collected in &8926 (comment 1127618337)

Do not document 5XX error codes

5XX error codes shouldn't be documented because we shouldn't be returning explicit 5XX errors, and clients have to assume that a server could return any 5XX error - they are, after all, server errors

How to document 4XX error codes

4XX codes seem to be very generic. Most endpoints will be able to respond with a 404 error. We can add a section about how to document those, or add a helper that adds the documentation automatically.