Add OpenAPI documentation for request endpoints

[krauselukas]

Replace this line with a description of your changes. Please follow the suggestions in the comment below.

---

If this PR requires any particular action or consideration before deployment,
please check the reasons or add your own to the list:

• Requires a database migration that can cause downtime. Postpone deployment until maintenance window[1].
• Contains a data migration that can cause temporary inconsistency, so should be run at a specific point of time.
• Changes some configuration files (e.g. options.yml), so the changes have to be applied manually in the reference server.
• A new Feature Toggle[2] should be enabled in the reference server.
• Proper documentation or announcement has to be published upfront since the introduced changes can confuse the users.

[1] https://github.com/openSUSE/open-build-service/wiki/Deployment-of-build.opensuse.org#when-there-are-migrations
[2] https://github.com/openSUSE/open-build-service/wiki/Feature-Toggles-%28Flipper%29#you-want-real-people-to-test-your-feature

[obs-bot]

Review app will appear here: http://obs-reviewlab.opensuse.org/krauselukas-api_docsrequest

[krauselukas]

Request

[dmarcoux]

We should add a note to the endpoints which are running expensive operations. The endpoint POST /request/{id}?cmd=diff is for sure one of them. I believe GET /request?view=collection could also be marked as such.

[dmarcoux]

I don't understand this sentence. Is this Get the diff for all packages affected in the request? I'm not sure.

[krauselukas]

You are right, the sentence is a bit off, will change it

[krauselukas]

I applied your suggestion :)

[krauselukas]

We should add a note to the endpoints which are running expensive operations. The endpoint POST /request/{id}?cmd=diff is for sure one of them. I believe GET /request?view=collection could also be marked as such.

Yes, might be a good idea to mention it, since its also mentioned in the general description of the API

[hennevogel]

Yes, might be a good idea to mention it, since its also mentioned in the general description of the API

No please. Calling an inexpensive operation 300 times concurrently is wrong the same way. Let's keep this simple.

[krauselukas]

Yes, might be a good idea to mention it, since its also mentioned in the general description of the API

No please. Calling an inexpensive operation 300 times concurrently is wrong the same way. Let's keep this simple.

True, haven't seen it from this perspective, lets keep it simple then 👍

[eduardoj]

Huge work! Thanks!

[krauselukas]

@eduardoj I addressed your review, please have another look :)

[eduardoj]

@eduardoj I addressed your review, please have another look :)

Looks good to me. Thanks a lot!