The REST API endpoint /rest/servicedeskapi/request/{issueIdOrKey}/attachment documentation needs to be fixed

Summary

The Documentation for the /rest/servicedeskapi/request/{issueIdOrKey}/attachment is incomplete and misleading. Indeed:

1. It is not immediate to understand that 2 different REST Calls are needed to attach a file to a JIRA Service Desk issue (one to attach the file to the Service Desk project, and one to attach it to the issue as explained in JSDECO-10
2. It contains a broken link to the endpoint servicedesk/{serviceDeskId}/attachTemporaryFile 
3. The example is using the key "get_public": "boolean" that does not exist. It is "public": "boolean" instead.
4. It says that, in order to use experimental methods, you must include the "X-ExperimentalApi: true" header in your requests. This works but when sending the request without the header to the instance, this replies saying that you should use "X-ExperimentalApi: opt-in". Both headers actually work (as you can see I have used both of them in below examples) but it should be mentioned in the doc.

Workaround/Solution:

1) You can achieve the same result by using the JIRA Core REST API endpoint to add an attachment to an issue as explained in:

• https://confluence.atlassian.com/jirakb/how-to-attach-an-attachment-in-a-jira-issue-using-rest-api-699957734.html/

2) You can use 2 calls to attach the files as in the below example (adding 2 attachments first to the project and then to the issue):

• Adding the files to the project (endpoint: servicedesk/{serviceDeskId}/attachTemporaryFile):

  curl -D- -u USER:PASSWORD -H "X-Atlassian-Token: nocheck" -H "X-ExperimentalApi: true" -F "file=@/path/to/file/test2.txt" -X POST https://INSTANCE.atlassian.net/rest/servicedeskapi/servicedesk/SERVICE_DESK_ID/attachTemporaryFile
  ....
  HTTP/1.1 100 Continue
  .....
  HTTP/1.1 201 Created
  ......
  {"temporaryAttachments":[{"temporaryAttachmentId":"5ad41f7b-882a-4f12-8a08-9b401d6dd3bf","fileName":"test2.txt"}]} 
  
  
  
  curl -D- -u USER:PASSWORD -H "X-Atlassian-Token: nocheck" -H "X-ExperimentalApi: opt-in" -F "file=@/path/to/file/test3.txt" -X POST https://INSTANCE.atlassian.net/rest/servicedeskapi/servicedesk/SERVICE_DESK_ID/attachTemporaryFile
  .....
  {"temporaryAttachments":[{"temporaryAttachmentId":"3f9ff4f9-99a0-4ee0-868e-8b93c8c67bee","fileName":"test3.txt"}]} 
  

• Adding the files to the issue (endpoint: /rest/servicedeskapi/request/{issueIdOrKey}/attachment):

  curl -D- -u USER:PASSWORD -H "Accept: application/json" -H "Content-Type: application/json" -H "X-ExperimentalApi: opt-in" -d '{"additionalComment": {"body": "TEST JSD ENDPOINT: adding 2 attachments"}, "public": "true","temporaryAttachmentIds": ["5ad41f7b-882a-4f12-8a08-9b401d6dd3bf", "3f9ff4f9-99a0-4ee0-868e-8b93c8c67bee"]}' -X POST https://INSTANCE.atlassian.net/rest/servicedeskapi/request/ISSUE_ID/attachment
  .....
  HTTP/1.1 201 Created
  .....
  {"comment":{"_expands":["attachment","renderedBody"],"id":"10504","body":"TEST JSD ENDPOINT: adding 2 attachments\n\n[^test2.txt] _(0.0 kB)_\n\n[^test3.txt] _(0.0 kB)_","public":true,...............}