API: Extract OpenAPI specification from source code using go-swagger (#40528) (#45061)

* API: Using go-swagger for extracting OpenAPI specification from source code

* Merge Grafana Alerting spec

* Include enterprise endpoints (if enabled)

* Serve SwaggerUI under feature flag

* Fix building dev docker images

* Configure swaggerUI

* Add missing json tags

Co-authored-by: Ying WANG <ying.wang@grafana.com>
Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>
(cherry picked from commit 35fe58de37)

pkg/api/dtos/acl.go

@@ -2,13 +2,21 @@ package dtos
 
 import "github.com/grafana/grafana/pkg/models"
 
+// swagger:model
 type UpdateDashboardAclCommand struct {
 	Items []DashboardAclUpdateItem `json:"items"`
 }
 
+// swagger:model
 type DashboardAclUpdateItem struct {
-	UserID     int64                 `json:"userId"`
-	TeamID     int64                 `json:"teamId"`
-	Role       *models.RoleType      `json:"role,omitempty"`
+	UserID int64            `json:"userId"`
+	TeamID int64            `json:"teamId"`
+	Role   *models.RoleType `json:"role,omitempty"`
+	// Permission level
+	// Description:
+	// * `1` - View
+	// * `2` - Edit
+	// * `4` - Admin
+	// Enum: 1,2,4
 	Permission models.PermissionType `json:"permission"`
 }

pkg/api/dtos/models.go

@@ -48,11 +48,25 @@ type CurrentUser struct {
 
 type UserPermissionsMap map[string]bool
 
+// swagger:model
 type MetricRequest struct {
-	From    string             `json:"from"`
-	To      string             `json:"to"`
+	// From Start time in epoch timestamps in milliseconds or relative using Grafana time units.
+	// required: true
+	// example: now-1h
+	From string `json:"from"`
+	// To End time in epoch timestamps in milliseconds or relative using Grafana time units.
+	// required: true
+	// example: now
+	To string `json:"to"`
+	// queries.refId – Specifies an identifier of the query. Is optional and default to “A”.
+	// queries.datasourceId – Specifies the data source to be queried. Each query in the request must have an unique datasourceId.
+	// queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100.
+	// queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.
+	// required: true
+	// example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasourceId": 86, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ]
 	Queries []*simplejson.Json `json:"queries"`
-	Debug   bool               `json:"debug"`
+	// required: false
+	Debug bool `json:"debug"`
 }
 
 func GetGravatarUrl(text string) string {

pkg/api/dtos/prefs.go

@@ -7,9 +7,14 @@ type Prefs struct {
 	WeekStart       string `json:"weekStart"`
 }
 
+// swagger:model
 type UpdatePrefsCmd struct {
-	Theme           string `json:"theme"`
-	HomeDashboardID int64  `json:"homeDashboardId"`
-	Timezone        string `json:"timezone"`
-	WeekStart       string `json:"weekStart"`
+	// Enum: light,dark
+	Theme string `json:"theme"`
+	// The numerical :id of a favorited dashboard
+	// Default:0
+	HomeDashboardID int64 `json:"homeDashboardId"`
+	// Enum: utc,browser
+	Timezone  string `json:"timezone"`
+	WeekStart string `json:"weekStart"`
 }