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

* 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>
2025-02-25 18:55:37 -06:00 · 2022-02-08 14:38:43 +02:00
parent 9c2363ef08
commit 35fe58de37
61 changed files with 35314 additions and 74 deletions
--- a/pkg/services/libraryelements/api.go
+++ b/pkg/services/libraryelements/api.go
@@ -83,7 +83,7 @@ func (l *LibraryElementService) getAllHandler(c *models.ReqContext) response.Res

 // patchHandler handles PATCH /api/library-elements/:uid
 func (l *LibraryElementService) patchHandler(c *models.ReqContext) response.Response {
-	cmd := patchLibraryElementCommand{}
+	cmd := PatchLibraryElementCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
 		return response.Error(http.StatusBadRequest, "bad request data", err)
 	}
--- a/pkg/services/libraryelements/database.go
+++ b/pkg/services/libraryelements/database.go
@@ -436,7 +436,7 @@ func (l *LibraryElementService) handleFolderIDPatches(ctx context.Context, eleme
 }

 // patchLibraryElement updates a Library Element.
-func (l *LibraryElementService) patchLibraryElement(c context.Context, signedInUser *models.SignedInUser, cmd patchLibraryElementCommand, uid string) (LibraryElementDTO, error) {
+func (l *LibraryElementService) patchLibraryElement(c context.Context, signedInUser *models.SignedInUser, cmd PatchLibraryElementCommand, uid string) (LibraryElementDTO, error) {
 	var dto LibraryElementDTO
 	if err := l.requireSupportedElementKind(cmd.Kind); err != nil {
 		return LibraryElementDTO{}, err
--- a/pkg/services/libraryelements/libraryelements_patch_test.go
+++ b/pkg/services/libraryelements/libraryelements_patch_test.go
@@ -14,7 +14,7 @@ import (
 func TestPatchLibraryElement(t *testing.T) {
 	scenarioWithPanel(t, "When an admin tries to patch a library panel that does not exist, it should fail",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{Kind: int64(models.PanelElement), Version: 1}
+			cmd := PatchLibraryElementCommand{Kind: int64(models.PanelElement), Version: 1}
 			sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": "unknown"})
 			sc.reqContext.Req.Body = mockRequestBody(cmd)
 			resp := sc.service.patchHandler(sc.reqContext)
@@ -24,7 +24,7 @@ func TestPatchLibraryElement(t *testing.T) {
 	scenarioWithPanel(t, "When an admin tries to patch a library panel that exists, it should succeed",
 		func(t *testing.T, sc scenarioContext) {
 			newFolder := createFolderWithACL(t, sc.sqlStore, "NewFolder", sc.user, []folderACLItem{})
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: newFolder.Id,
 				Name:     "Panel - New name",
 				Model: []byte(`
@@ -87,7 +87,7 @@ func TestPatchLibraryElement(t *testing.T) {
 	scenarioWithPanel(t, "When an admin tries to patch a library panel with folder only, it should change folder successfully and return correct result",
 		func(t *testing.T, sc scenarioContext) {
 			newFolder := createFolderWithACL(t, sc.sqlStore, "NewFolder", sc.user, []folderACLItem{})
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: newFolder.Id,
 				Kind:     int64(models.PanelElement),
 				Version:  1,
@@ -109,7 +109,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with name only, it should change name successfully and return correct result",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				Name:     "New Name",
 				Kind:     int64(models.PanelElement),
@@ -132,7 +132,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with a nonexistent UID, it should change UID successfully and return correct result",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				UID:      util.GenerateShortUID(),
 				Kind:     int64(models.PanelElement),
@@ -155,7 +155,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with an invalid UID, it should fail",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				UID:      "Testing an invalid UID",
 				Kind:     int64(models.PanelElement),
@@ -169,7 +169,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with an UID that is too long, it should fail",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				UID:      "j6T00KRZzj6T00KRZzj6T00KRZzj6T00KRZzj6T00K",
 				Kind:     int64(models.PanelElement),
@@ -188,7 +188,7 @@ func TestPatchLibraryElement(t *testing.T) {
 			sc.reqContext.Req.Body = mockRequestBody(command)
 			resp := sc.service.createHandler(sc.reqContext)
 			require.Equal(t, 200, resp.Status())
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				UID:      command.UID,
 				Kind:     int64(models.PanelElement),
@@ -202,7 +202,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with model only, it should change model successfully, sync type and description fields and return correct result",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				Model:    []byte(`{ "title": "New Model Title", "name": "New Model Name", "type":"graph", "description": "New description" }`),
 				Kind:     int64(models.PanelElement),
@@ -231,7 +231,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with model.description only, it should change model successfully, sync type and description fields and return correct result",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				Model:    []byte(`{ "description": "New description" }`),
 				Kind:     int64(models.PanelElement),
@@ -258,7 +258,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with model.type only, it should change model successfully, sync type and description fields and return correct result",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: -1,
 				Model:    []byte(`{ "type": "graph" }`),
 				Kind:     int64(models.PanelElement),
@@ -285,7 +285,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When another admin tries to patch a library panel, it should change UpdatedBy successfully and return correct result",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{FolderID: -1, Version: 1, Kind: int64(models.PanelElement)}
+			cmd := PatchLibraryElementCommand{FolderID: -1, Version: 1, Kind: int64(models.PanelElement)}
 			sc.reqContext.UserId = 2
 			sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": sc.initialResult.Result.UID})
 			sc.ctx.Req.Body = mockRequestBody(cmd)
@@ -307,7 +307,7 @@ func TestPatchLibraryElement(t *testing.T) {
 			sc.ctx.Req.Body = mockRequestBody(command)
 			resp := sc.service.createHandler(sc.reqContext)
 			var result = validateAndUnMarshalResponse(t, resp)
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				Name:    "Text - Library Panel",
 				Version: 1,
 				Kind:    int64(models.PanelElement),
@@ -325,7 +325,7 @@ func TestPatchLibraryElement(t *testing.T) {
 			sc.ctx.Req.Body = mockRequestBody(command)
 			resp := sc.service.createHandler(sc.reqContext)
 			var result = validateAndUnMarshalResponse(t, resp)
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: 1,
 				Version:  1,
 				Kind:     int64(models.PanelElement),
@@ -338,7 +338,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel in another org, it should fail",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: sc.folder.Id,
 				Version:  1,
 				Kind:     int64(models.PanelElement),
@@ -352,7 +352,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with an old version number, it should fail",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: sc.folder.Id,
 				Version:  1,
 				Kind:     int64(models.PanelElement),
@@ -368,7 +368,7 @@ func TestPatchLibraryElement(t *testing.T) {

 	scenarioWithPanel(t, "When an admin tries to patch a library panel with an other kind, it should succeed but panel should not change",
 		func(t *testing.T, sc scenarioContext) {
-			cmd := patchLibraryElementCommand{
+			cmd := PatchLibraryElementCommand{
 				FolderID: sc.folder.Id,
 				Version:  1,
 				Kind:     int64(models.VariableElement),
--- a/pkg/services/libraryelements/libraryelements_permissions_test.go
+++ b/pkg/services/libraryelements/libraryelements_permissions_test.go
@@ -86,7 +86,7 @@ func TestLibraryElementPermissions(t *testing.T) {
 				toFolder := createFolderWithACL(t, sc.sqlStore, "Folder", sc.user, testCase.items)
 				sc.reqContext.SignedInUser.OrgRole = testCase.role

-				cmd := patchLibraryElementCommand{FolderID: toFolder.Id, Version: 1, Kind: int64(models.PanelElement)}
+				cmd := PatchLibraryElementCommand{FolderID: toFolder.Id, Version: 1, Kind: int64(models.PanelElement)}
 				sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": result.Result.UID})
 				sc.reqContext.Req.Body = mockRequestBody(cmd)
 				resp = sc.service.patchHandler(sc.reqContext)
@@ -103,7 +103,7 @@ func TestLibraryElementPermissions(t *testing.T) {
 				toFolder := createFolderWithACL(t, sc.sqlStore, "Folder", sc.user, everyonePermissions)
 				sc.reqContext.SignedInUser.OrgRole = testCase.role

-				cmd := patchLibraryElementCommand{FolderID: toFolder.Id, Version: 1, Kind: int64(models.PanelElement)}
+				cmd := PatchLibraryElementCommand{FolderID: toFolder.Id, Version: 1, Kind: int64(models.PanelElement)}
 				sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": result.Result.UID})
 				sc.reqContext.Req.Body = mockRequestBody(cmd)
 				resp = sc.service.patchHandler(sc.reqContext)
@@ -154,7 +154,7 @@ func TestLibraryElementPermissions(t *testing.T) {
 				result := validateAndUnMarshalResponse(t, resp)
 				sc.reqContext.SignedInUser.OrgRole = testCase.role

-				cmd := patchLibraryElementCommand{FolderID: 0, Version: 1, Kind: int64(models.PanelElement)}
+				cmd := PatchLibraryElementCommand{FolderID: 0, Version: 1, Kind: int64(models.PanelElement)}
 				sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": result.Result.UID})
 				sc.ctx.Req.Body = mockRequestBody(cmd)
 				resp = sc.service.patchHandler(sc.reqContext)
@@ -170,7 +170,7 @@ func TestLibraryElementPermissions(t *testing.T) {
 				result := validateAndUnMarshalResponse(t, resp)
 				sc.reqContext.SignedInUser.OrgRole = testCase.role

-				cmd := patchLibraryElementCommand{FolderID: folder.Id, Version: 1, Kind: int64(models.PanelElement)}
+				cmd := PatchLibraryElementCommand{FolderID: folder.Id, Version: 1, Kind: int64(models.PanelElement)}
 				sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": result.Result.UID})
 				sc.ctx.Req.Body = mockRequestBody(cmd)
 				resp = sc.service.patchHandler(sc.reqContext)
@@ -219,7 +219,7 @@ func TestLibraryElementPermissions(t *testing.T) {
 				result := validateAndUnMarshalResponse(t, resp)
 				sc.reqContext.SignedInUser.OrgRole = testCase.role

-				cmd := patchLibraryElementCommand{FolderID: -100, Version: 1, Kind: int64(models.PanelElement)}
+				cmd := PatchLibraryElementCommand{FolderID: -100, Version: 1, Kind: int64(models.PanelElement)}
 				sc.ctx.Req = web.SetURLParams(sc.ctx.Req, map[string]string{":uid": result.Result.UID})
 				sc.reqContext.Req.Body = mockRequestBody(cmd)
 				resp = sc.service.patchHandler(sc.reqContext)
--- a/pkg/services/libraryelements/models.go
+++ b/pkg/services/libraryelements/models.go
@@ -158,22 +158,43 @@ var (
 // Commands

 // CreateLibraryElementCommand is the command for adding a LibraryElement
+// swagger:model
 type CreateLibraryElementCommand struct {
-	FolderID int64           `json:"folderId"`
-	Name     string          `json:"name"`
-	Model    json.RawMessage `json:"model"`
-	Kind     int64           `json:"kind" binding:"Required"`
-	UID      string          `json:"uid"`
+	// ID of the folder where the library element is stored.
+	FolderID int64 `json:"folderId"`
+	// Name of the library element.
+	Name string `json:"name"`
+	// The JSON model for the library element.
+	// swagger:type object
+	Model json.RawMessage `json:"model"`
+	// Kind of element to create, Use 1 for library panels or 2 for c.
+	// Description:
+	// * 1 - library panels
+	// * 2 - library variables
+	// Enum: 1,2
+	Kind int64 `json:"kind" binding:"Required"`
+	// required: false
+	UID string `json:"uid"`
 }

-// patchLibraryElementCommand is the command for patching a LibraryElement
-type patchLibraryElementCommand struct {
-	FolderID int64           `json:"folderId" binding:"Default(-1)"`
-	Name     string          `json:"name"`
-	Model    json.RawMessage `json:"model,omitempty"`
-	Kind     int64           `json:"kind" binding:"Required"`
-	Version  int64           `json:"version" binding:"Required"`
-	UID      string          `json:"uid"`
+// PatchLibraryElementCommand is the command for patching a LibraryElement
+type PatchLibraryElementCommand struct {
+	// ID of the folder where the library element is stored.
+	FolderID int64 `json:"folderId" binding:"Default(-1)"`
+	// Name of the library element.
+	Name string `json:"name"`
+	// The JSON model for the library element.
+	Model json.RawMessage `json:"model,omitempty"`
+	// Kind of element to create, Use 1 for library panels or 2 for c.
+	// Description:
+	// * 1 - library panels
+	// * 2 - library variables
+	// Enum: 1,2
+	Kind int64 `json:"kind" binding:"Required"`
+	// Version of the library element you are updating.
+	Version int64 `json:"version" binding:"Required"`
+	// required: false
+	UID string `json:"uid"`
 }

 // searchLibraryElementsQuery is the query used for searching for Elements