fix: correct swagger description for Insights API (#13442)

coderd/apidoc/docs.go

@@ -1158,6 +1158,15 @@ const docTemplate = `{
                 ],
                 "summary": "Get deployment DAUs",
                 "operationId": "get-deployment-daus",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Time-zone offset (e.g. -2)",
+                        "name": "tz_offset",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -1185,18 +1194,41 @@ const docTemplate = `{
                 "operationId": "get-insights-about-templates",
                 "parameters": [
                     {
-                        "type": "integer",
+                        "type": "string",
+                        "format": "date-time",
                         "description": "Start time",
-                        "name": "before",
+                        "name": "start_time",
                         "in": "query",
                         "required": true
                     },
                     {
-                        "type": "integer",
+                        "type": "string",
+                        "format": "date-time",
                         "description": "End time",
-                        "name": "after",
+                        "name": "end_time",
                         "in": "query",
                         "required": true
+                    },
+                    {
+                        "enum": [
+                            "week",
+                            "day"
+                        ],
+                        "type": "string",
+                        "description": "Interval",
+                        "name": "interval",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "collectionFormat": "csv",
+                        "description": "Template IDs",
+                        "name": "template_ids",
+                        "in": "query"
                     }
                 ],
                 "responses": {
@@ -1226,18 +1258,30 @@ const docTemplate = `{
                 "operationId": "get-insights-about-user-activity",
                 "parameters": [
                     {
-                        "type": "integer",
+                        "type": "string",
+                        "format": "date-time",
                         "description": "Start time",
-                        "name": "before",
+                        "name": "start_time",
                         "in": "query",
                         "required": true
                     },
                     {
-                        "type": "integer",
+                        "type": "string",
+                        "format": "date-time",
                         "description": "End time",
-                        "name": "after",
+                        "name": "end_time",
                         "in": "query",
                         "required": true
+                    },
+                    {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "collectionFormat": "csv",
+                        "description": "Template IDs",
+                        "name": "template_ids",
+                        "in": "query"
                     }
                 ],
                 "responses": {
@@ -1267,18 +1311,30 @@ const docTemplate = `{
                 "operationId": "get-insights-about-user-latency",
                 "parameters": [
                     {
-                        "type": "integer",
+                        "type": "string",
+                        "format": "date-time",
                         "description": "Start time",
-                        "name": "before",
+                        "name": "start_time",
                         "in": "query",
                         "required": true
                     },
                     {
-                        "type": "integer",
+                        "type": "string",
+                        "format": "date-time",
                         "description": "End time",
-                        "name": "after",
+                        "name": "end_time",
                         "in": "query",
                         "required": true
+                    },
+                    {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "collectionFormat": "csv",
+                        "description": "Template IDs",
+                        "name": "template_ids",
+                        "in": "query"
                     }
                 ],
                 "responses": {

coderd/apidoc/swagger.json

@@ -998,6 +998,15 @@
         "tags": ["Insights"],
         "summary": "Get deployment DAUs",
         "operationId": "get-deployment-daus",
+        "parameters": [
+          {
+            "type": "integer",
+            "description": "Time-zone offset (e.g. -2)",
+            "name": "tz_offset",
+            "in": "query",
+            "required": true
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK",
@@ -1021,18 +1030,38 @@
         "operationId": "get-insights-about-templates",
         "parameters": [
           {
-            "type": "integer",
+            "type": "string",
+            "format": "date-time",
             "description": "Start time",
-            "name": "before",
+            "name": "start_time",
             "in": "query",
             "required": true
           },
           {
-            "type": "integer",
+            "type": "string",
+            "format": "date-time",
             "description": "End time",
-            "name": "after",
+            "name": "end_time",
             "in": "query",
             "required": true
+          },
+          {
+            "enum": ["week", "day"],
+            "type": "string",
+            "description": "Interval",
+            "name": "interval",
+            "in": "query",
+            "required": true
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "collectionFormat": "csv",
+            "description": "Template IDs",
+            "name": "template_ids",
+            "in": "query"
           }
         ],
         "responses": {
@@ -1058,18 +1087,30 @@
         "operationId": "get-insights-about-user-activity",
         "parameters": [
           {
-            "type": "integer",
+            "type": "string",
+            "format": "date-time",
             "description": "Start time",
-            "name": "before",
+            "name": "start_time",
             "in": "query",
             "required": true
           },
           {
-            "type": "integer",
+            "type": "string",
+            "format": "date-time",
             "description": "End time",
-            "name": "after",
+            "name": "end_time",
             "in": "query",
             "required": true
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "collectionFormat": "csv",
+            "description": "Template IDs",
+            "name": "template_ids",
+            "in": "query"
           }
         ],
         "responses": {
@@ -1095,18 +1136,30 @@
         "operationId": "get-insights-about-user-latency",
         "parameters": [
           {
-            "type": "integer",
+            "type": "string",
+            "format": "date-time",
             "description": "Start time",
-            "name": "before",
+            "name": "start_time",
             "in": "query",
             "required": true
           },
           {
-            "type": "integer",
+            "type": "string",
+            "format": "date-time",
             "description": "End time",
-            "name": "after",
+            "name": "end_time",
             "in": "query",
             "required": true
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "collectionFormat": "csv",
+            "description": "Template IDs",
+            "name": "template_ids",
+            "in": "query"
           }
         ],
         "responses": {

coderd/insights.go

@@ -30,6 +30,7 @@ const insightsTimeLayout = time.RFC3339
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Insights
+// @Param tz_offset query int true "Time-zone offset (e.g. -2)"
 // @Success 200 {object} codersdk.DAUsResponse
 // @Router /insights/daus [get]
 func (api *API) deploymentDAUs(rw http.ResponseWriter, r *http.Request) {
@@ -100,8 +101,9 @@ func (api *API) returnDAUsInternal(rw http.ResponseWriter, r *http.Request, temp
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Insights
-// @Param before query int true "Start time"
+// @Param start_time query string true "Start time" format(date-time)
-// @Param after query int true "End time"
+// @Param end_time query string true "End time" format(date-time)
+// @Param template_ids query []string false "Template IDs" collectionFormat(csv)
 // @Success 200 {object} codersdk.UserActivityInsightsResponse
 // @Router /insights/user-activity [get]
 func (api *API) insightsUserActivity(rw http.ResponseWriter, r *http.Request) {
@@ -202,8 +204,9 @@ func (api *API) insightsUserActivity(rw http.ResponseWriter, r *http.Request) {
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Insights
-// @Param before query int true "Start time"
+// @Param start_time query string true "Start time" format(date-time)
-// @Param after query int true "End time"
+// @Param end_time query string true "End time" format(date-time)
+// @Param template_ids query []string false "Template IDs" collectionFormat(csv)
 // @Success 200 {object} codersdk.UserLatencyInsightsResponse
 // @Router /insights/user-latency [get]
 func (api *API) insightsUserLatency(rw http.ResponseWriter, r *http.Request) {
@@ -294,8 +297,10 @@ func (api *API) insightsUserLatency(rw http.ResponseWriter, r *http.Request) {
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Insights
-// @Param before query int true "Start time"
+// @Param start_time query string true "Start time" format(date-time)
-// @Param after query int true "End time"
+// @Param end_time query string true "End time" format(date-time)
+// @Param interval query string true "Interval" enums(week,day)
+// @Param template_ids query []string false "Template IDs" collectionFormat(csv)
 // @Success 200 {object} codersdk.TemplateInsightsResponse
 // @Router /insights/templates [get]
 func (api *API) insightsTemplates(rw http.ResponseWriter, r *http.Request) {

docs/api/insights.md

@@ -6,13 +6,19 @@
 
 ```shell
 # Example request using curl
-curl -X GET http://coder-server:8080/api/v2/insights/daus \
+curl -X GET http://coder-server:8080/api/v2/insights/daus?tz_offset=0 \
   -H 'Accept: application/json' \
   -H 'Coder-Session-Token: API_KEY'
 ```
 
 `GET /insights/daus`
 
+### Parameters
+
+| Name        | In    | Type    | Required | Description                |
+| ----------- | ----- | ------- | -------- | -------------------------- |
+| `tz_offset` | query | integer | true     | Time-zone offset (e.g. -2) |
+
 ### Example responses
 
 > 200 Response
@@ -43,7 +49,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio
 
 ```shell
 # Example request using curl
-curl -X GET http://coder-server:8080/api/v2/insights/templates?before=0&after=0 \
+curl -X GET http://coder-server:8080/api/v2/insights/templates?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z&interval=week \
   -H 'Accept: application/json' \
   -H 'Coder-Session-Token: API_KEY'
 ```
@@ -52,10 +58,19 @@ curl -X GET http://coder-server:8080/api/v2/insights/templates?before=0&after=0
 
 ### Parameters
 
-| Name     | In    | Type    | Required | Description |
+| Name           | In    | Type              | Required | Description  |
-| -------- | ----- | ------- | -------- | ----------- |
+| -------------- | ----- | ----------------- | -------- | ------------ |
-| `before` | query | integer | true     | Start time  |
+| `start_time`   | query | string(date-time) | true     | Start time   |
-| `after`  | query | integer | true     | End time    |
+| `end_time`     | query | string(date-time) | true     | End time     |
+| `interval`     | query | string            | true     | Interval     |
+| `template_ids` | query | array[string]     | false    | Template IDs |
+
+#### Enumerated Values
+
+| Parameter  | Value  |
+| ---------- | ------ |
+| `interval` | `week` |
+| `interval` | `day`  |
 
 ### Example responses
 
@@ -129,7 +144,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio
 
 ```shell
 # Example request using curl
-curl -X GET http://coder-server:8080/api/v2/insights/user-activity?before=0&after=0 \
+curl -X GET http://coder-server:8080/api/v2/insights/user-activity?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z \
   -H 'Accept: application/json' \
   -H 'Coder-Session-Token: API_KEY'
 ```
@@ -138,10 +153,11 @@ curl -X GET http://coder-server:8080/api/v2/insights/user-activity?before=0&afte
 
 ### Parameters
 
-| Name     | In    | Type    | Required | Description |
+| Name           | In    | Type              | Required | Description  |
-| -------- | ----- | ------- | -------- | ----------- |
+| -------------- | ----- | ----------------- | -------- | ------------ |
-| `before` | query | integer | true     | Start time  |
+| `start_time`   | query | string(date-time) | true     | Start time   |
-| `after`  | query | integer | true     | End time    |
+| `end_time`     | query | string(date-time) | true     | End time     |
+| `template_ids` | query | array[string]     | false    | Template IDs |
 
 ### Example responses
 
@@ -180,7 +196,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio
 
 ```shell
 # Example request using curl
-curl -X GET http://coder-server:8080/api/v2/insights/user-latency?before=0&after=0 \
+curl -X GET http://coder-server:8080/api/v2/insights/user-latency?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z \
   -H 'Accept: application/json' \
   -H 'Coder-Session-Token: API_KEY'
 ```
@@ -189,10 +205,11 @@ curl -X GET http://coder-server:8080/api/v2/insights/user-latency?before=0&after
 
 ### Parameters
 
-| Name     | In    | Type    | Required | Description |
+| Name           | In    | Type              | Required | Description  |
-| -------- | ----- | ------- | -------- | ----------- |
+| -------------- | ----- | ----------------- | -------- | ------------ |
-| `before` | query | integer | true     | Start time  |
+| `start_time`   | query | string(date-time) | true     | Start time   |
-| `after`  | query | integer | true     | End time    |
+| `end_time`     | query | string(date-time) | true     | End time     |
+| `template_ids` | query | array[string]     | false    | Template IDs |
 
 ### Example responses