API: Make Swagger specification more consistent (#50576)

* Fix swagger generation targer using mac

Validate using the swagger binarry instead of the docker container

* API: Make swagger specification more consistent

Fix operation parameter ordering

pkg/api/docs/definitions/annotations.go

@@ -113,8 +113,15 @@ import (
 // 401: unauthorisedError
 // 500: internalServerError
 
-// swagger:parameters getAnnotation updateAnnotation patchAnnotation deleteAnnotation
-type AnnotationIDParam struct {
+// swagger:parameters getAnnotation
+type GetAnnotationParams struct {
+	// in:path
+	// required:true
+	AnnotationID string `json:"annotation_id"`
+}
+
+// swagger:parameters deleteAnnotation
+type DeleteAnnotationParams struct {
 	// in:path
 	// required:true
 	AnnotationID string `json:"annotation_id"`
@@ -206,6 +213,9 @@ type CreateGraphiteAnnotationParams struct {
 
 // swagger:parameters updateAnnotation
 type UpdateAnnotationParams struct {
+	// in:path
+	// required:true
+	AnnotationID string `json:"annotation_id"`
 	// in:body
 	// required:true
 	Body dtos.UpdateAnnotationsCmd `json:"body"`
@@ -213,6 +223,9 @@ type UpdateAnnotationParams struct {
 
 // swagger:parameters patchAnnotation
 type PatchAnnotationParams struct {
+	// in:path
+	// required:true
+	AnnotationID string `json:"annotation_id"`
 	// in:body
 	// required:true
 	Body dtos.PatchAnnotationsCmd `json:"body"`