From c56aae6f63ce68e0ea11041112c5b4f7ffd0d7eb Mon Sep 17 00:00:00 2001
From: Harry Tennent <71338309+HarryTennent@users.noreply.github.com>
Date: Wed, 3 Aug 2022 09:01:25 +0100
Subject: [PATCH] Docs: update annotations API docs to include required field
 (#52644)

* Update annotations.md

A minor change to include the required fields when creating a new annotation via the annotations API. The error message when fields are missing is not descriptive and there is no indication in the current documentation (that I can see anyway) that would indicate these fields are required.

* Update annotations.md

Update required json body fields to only include fields that are actually required.

* Add required field in Swagger

Co-authored-by: Sofia Papagiannaki <1632407+papagian@users.noreply.github.com>
---
 docs/sources/developers/http_api/annotations.md |  4 ++++
 pkg/api/dtos/annotations.go                     | 17 +++++++++--------
 public/api-merged.json                          |  1 +
 public/api-spec.json                            |  1 +
 4 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/sources/developers/http_api/annotations.md b/docs/sources/developers/http_api/annotations.md
index c0cd017b6b7..a7314df7905 100644
--- a/docs/sources/developers/http_api/annotations.md
+++ b/docs/sources/developers/http_api/annotations.md
@@ -122,6 +122,10 @@ See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanatio
 | ------------------ | ----------------------- |
 | annotations:create | annotations:type:<type> |
 
+**Required JSON Body Fields**
+
+- `text`: description of the annotation.
+
 **Example Request**:
 
 ```http
diff --git a/pkg/api/dtos/annotations.go b/pkg/api/dtos/annotations.go
index 1f480334494..1235e077bea 100644
--- a/pkg/api/dtos/annotations.go
+++ b/pkg/api/dtos/annotations.go
@@ -3,14 +3,15 @@ package dtos
 import "github.com/grafana/grafana/pkg/components/simplejson"
 
 type PostAnnotationsCmd struct {
-	DashboardId  int64            `json:"dashboardId"`
-	DashboardUID string           `json:"dashboardUID,omitempty"`
-	PanelId      int64            `json:"panelId"`
-	Time         int64            `json:"time"`
-	TimeEnd      int64            `json:"timeEnd,omitempty"` // Optional
-	Text         string           `json:"text"`
-	Tags         []string         `json:"tags"`
-	Data         *simplejson.Json `json:"data"`
+	DashboardId  int64  `json:"dashboardId"`
+	DashboardUID string `json:"dashboardUID,omitempty"`
+	PanelId      int64  `json:"panelId"`
+	Time         int64  `json:"time"`
+	TimeEnd      int64  `json:"timeEnd,omitempty"` // Optional
+	// required: true
+	Text string           `json:"text"`
+	Tags []string         `json:"tags"`
+	Data *simplejson.Json `json:"data"`
 }
 
 type UpdateAnnotationsCmd struct {
diff --git a/public/api-merged.json b/public/api-merged.json
index f7d052cb916..908510961ef 100644
--- a/public/api-merged.json
+++ b/public/api-merged.json
@@ -14150,6 +14150,7 @@
     },
     "PostAnnotationsCmd": {
       "type": "object",
+      "required": ["text"],
       "properties": {
         "dashboardId": {
           "type": "integer",
diff --git a/public/api-spec.json b/public/api-spec.json
index 5c01a5b4bbd..9957b5cd237 100644
--- a/public/api-spec.json
+++ b/public/api-spec.json
@@ -12099,6 +12099,7 @@
     },
     "PostAnnotationsCmd": {
       "type": "object",
+      "required": ["text"],
       "properties": {
         "dashboardId": {
           "type": "integer",