From 8aae7be4e594fc87a9fa5f0288489aafb2ac8e12 Mon Sep 17 00:00:00 2001 From: Sofia Papagiannaki <1632407+papagian@users.noreply.github.com> Date: Wed, 1 Mar 2023 16:36:37 +0200 Subject: [PATCH] API: Enable serving Swagger UI by default and add docs and guidelines (#63489) * Enable serving Swagger UI by default It used to be served behind the `swaggerUi` feature toggle. * Remove `swaggerUi` feature toggle * Add docs and guidelines for updating swagger * Apply suggestions from code review Co-authored-by: Josh Hunt --- contribute/backend/README.md | 1 + docs/sources/developers/http_api/_index.md | 6 ++ .../feature-toggles/index.md | 1 - .../src/types/featureToggles.gen.ts | 1 - pkg/api/README.md | 82 +++++++++++++++++++ pkg/api/api.go | 6 +- pkg/services/featuremgmt/registry.go | 5 -- pkg/services/featuremgmt/toggles_gen.go | 4 - 8 files changed, 91 insertions(+), 15 deletions(-) create mode 100644 pkg/api/README.md diff --git a/contribute/backend/README.md b/contribute/backend/README.md index 225a435ae77..3a26265bc83 100644 --- a/contribute/backend/README.md +++ b/contribute/backend/README.md @@ -13,6 +13,7 @@ of content of the following files is expected: - [Services](/contribute/backend/services.md) - [Communication](/contribute/backend/communication.md) - [Database](/contribute/backend/database.md) +- [HTTP API](/pkg/api/README.md) Reviewers who review large changes should additionally make a habit out of familiarizing themselves with the content of diff --git a/docs/sources/developers/http_api/_index.md b/docs/sources/developers/http_api/_index.md index 704b52e40f6..711aa1655bb 100644 --- a/docs/sources/developers/http_api/_index.md +++ b/docs/sources/developers/http_api/_index.md @@ -19,6 +19,12 @@ weight: 100 The Grafana backend exposes an HTTP API, which is the same API that is used by the frontend to do everything from saving dashboards, creating users, and updating data sources. +Since version 8.4, HTTP API details are [specified](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/api-merged.json) using OpenAPI v2. + +Starting from version 9.1, there is also a [OpenAPI v3 specification](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/openapi3.json) (generated by the v2 one). + +Users can browser and try out both via the Swagger UI editor (served by the grafana server) by navigating to `/swagger-ui` and `/openapi3` respectively. + ## HTTP APIs - [Admin API]({{< relref "admin/" >}}) diff --git a/docs/sources/setup-grafana/configure-grafana/feature-toggles/index.md b/docs/sources/setup-grafana/configure-grafana/feature-toggles/index.md index 4a0a1882de9..9d62292c479 100644 --- a/docs/sources/setup-grafana/configure-grafana/feature-toggles/index.md +++ b/docs/sources/setup-grafana/configure-grafana/feature-toggles/index.md @@ -38,7 +38,6 @@ Some stable features are enabled by default. You can disable a stable feature by | `trimDefaults` | Use cue schema to remove values that will be applied automatically | | `panelTitleSearch` | Search for dashboards using panel title | | `prometheusAzureOverrideAudience` | Experimental. Allow override default AAD audience for Azure Prometheus endpoint | -| `swaggerUi` | Serves swagger UI | | `migrationLocking` | Lock database during migrations | | `newDBLibrary` | Use jmoiron/sqlx rather than xorm for a few backend services | | `validateDashboardsOnSave` | Validate dashboard JSON POSTed to api/dashboards/db | diff --git a/packages/grafana-data/src/types/featureToggles.gen.ts b/packages/grafana-data/src/types/featureToggles.gen.ts index 91016960352..53774b6f6b0 100644 --- a/packages/grafana-data/src/types/featureToggles.gen.ts +++ b/packages/grafana-data/src/types/featureToggles.gen.ts @@ -30,7 +30,6 @@ export interface FeatureToggles { publicDashboardsEmailSharing?: boolean; lokiLive?: boolean; lokiDataframeApi?: boolean; - swaggerUi?: boolean; featureHighlights?: boolean; dashboardComments?: boolean; annotationComments?: boolean; diff --git a/pkg/api/README.md b/pkg/api/README.md new file mode 100644 index 00000000000..8769ab91dba --- /dev/null +++ b/pkg/api/README.md @@ -0,0 +1,82 @@ +# OpenAPI specifications + +Since version 8.4, HTTP API details are [specified](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/api-merged.json) using OpenAPI v2. Starting from version 9.1, there is also an [OpenAPI v3 specification](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/openapi3.json) (generated by the v2 one using [this script](https://github.com/grafana/grafana/blob/main/scripts/openapi3/openapi3conv.go)). + +# OpenAPI annotations + +The OpenAPI v2 specification is generated automatically from the annotated Go code using [go-swagger](https://github.com/go-swagger/go-swagger) which scans the source code for [annotation rules](https://goswagger.io/use/spec.html). Refer to [this getting started guide](https://medium.com/@pedram.esmaeeli/generate-swagger-specification-from-go-source-code-648615f7b9d9) for getting familiar with the toolkit. + +Developers modifying the HTTP API endpoints need to make sure to add the necessary annotations so that their changes are reflected into the generated specifications. + +## Example of endpoint annotation + +The following route defines a `PATCH` endpoint under the `/serviceaccounts/{serviceAccountId}` path with tag `service_accounts` (used for grouping together several routes) and operation ID `updateServiceAccount` (used for uniquely identifying routes and associate parameters and response with them). + +```go + +// swagger:route PATCH /serviceaccounts/{serviceAccountId} service_accounts updateServiceAccount +// +// # Update service account +// +// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation): +// action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account) +// +// Responses: +// 200: updateServiceAccountResponse +// 400: badRequestError +// 401: unauthorisedError +// 403: forbiddenError +// 404: notFoundError +// 500: internalServerError + +``` + +The `go-swagger` can discover such annotations by scanning any code imported by [`pkg/server`](https://github.com/grafana/grafana/blob/main/pkg/server/server.go) but by convention we place the endpoint annotations above the endpoint definition. + +## Example of endpoint parameters + +The following struct defines the route parameters for the `updateServiceAccount` endpoint. The route expects: +* a path parameter denoting the service account identifier and +* a body parameter with the new values for the specific service account + +```go + +// swagger:parameters updateServiceAccount +type UpdateServiceAccountParams struct { + // in:path + ServiceAccountId int64 `json:"serviceAccountId"` + // in:body + Body serviceaccounts.UpdateServiceAccountForm +} +``` + +## Example of endpoint response + +The following struct defines the response for the `updateServiceAccount` endpoint in case of a successful `200` response. + +```go + +// swagger:response updateServiceAccountResponse +type UpdateServiceAccountResponse struct { + // in:body + Body struct { + Message string `json:"message"` + ID int64 `json:"id"` + Name string `json:"name"` + ServiceAccount *serviceaccounts.ServiceAccountProfileDTO `json:"serviceaccount"` + } +} +``` + +# OpenAPI generation + +Developers can re-create the OpenAPI v2 and v3 specifications using the following command: + +```bash + +make clean-api-spec && make openapi3-gen +``` + +They can observe its output into the `public/api-merged.json` and `public/openapi3.json` files. + +Finally, they can browser and try out both the OpenAPI v2 and v3 via the Swagger UI editor (served by the grafana server) by navigating to `/swagger-ui` and `/openapi3` respectivally. diff --git a/pkg/api/api.go b/pkg/api/api.go index 2d07d864d9d..8a9b6248415 100644 --- a/pkg/api/api.go +++ b/pkg/api/api.go @@ -218,10 +218,8 @@ func (hs *HTTPServer) registerRoutes() { // expose plugin file system assets r.Get("/public/plugins/:pluginId/*", hs.getPluginAssets) - if hs.Features.IsEnabled(featuremgmt.FlagSwaggerUi) { - r.Get("/swagger-ui", swaggerUI) - r.Get("/openapi3", openapi3) - } + r.Get("/swagger-ui", swaggerUI) + r.Get("/openapi3", openapi3) // authed api r.Group("/api", func(apiRoute routing.RouteRegister) { diff --git a/pkg/services/featuremgmt/registry.go b/pkg/services/featuremgmt/registry.go index 81e33117091..70b56370717 100644 --- a/pkg/services/featuremgmt/registry.go +++ b/pkg/services/featuremgmt/registry.go @@ -83,11 +83,6 @@ var ( Description: "Use experimental loki api for WebSocket streaming (early prototype)", State: FeatureStateAlpha, }, - { - Name: "swaggerUi", - Description: "Serves swagger UI", - State: FeatureStateBeta, - }, { Name: "featureHighlights", Description: "Highlight Grafana Enterprise features", diff --git a/pkg/services/featuremgmt/toggles_gen.go b/pkg/services/featuremgmt/toggles_gen.go index ca21ad947c2..4781421e7eb 100644 --- a/pkg/services/featuremgmt/toggles_gen.go +++ b/pkg/services/featuremgmt/toggles_gen.go @@ -63,10 +63,6 @@ const ( // Use experimental loki api for WebSocket streaming (early prototype) FlagLokiDataframeApi = "lokiDataframeApi" - // FlagSwaggerUi - // Serves swagger UI - FlagSwaggerUi = "swaggerUi" - // FlagFeatureHighlights // Highlight Grafana Enterprise features FlagFeatureHighlights = "featureHighlights"