docs: audit, deploymentconfig, files, parameters

coder · mtojek · Jan 11, 2023 · Dec 22, 2022 · Jan 2, 2023 · Jan 2, 2023
commit a3fbe72717ee213e0cabf36cebbefd3a8130a82e
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/audit.go b/coderd/audit.go
@@ -24,6 +24,17 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Get audit logs
+// @ID get-audit-logs
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Audit
+// @Param q query string true "Search query"
+// @Param after_id query string false "After ID" format(uuid)
+// @Param limit query int false "Page limit"
+// @Param offset query int false "Page offset"
+// @Success 200 {object} codersdk.AuditLogResponse
+// @Router /audit [get]
 func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	if !api.Authorize(r, rbac.ActionRead, rbac.ResourceAuditLog) {
@@ -77,6 +88,14 @@ func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// @Summary Generate fake audit log
+// @ID generate-fake-audit-logs
+// @Security CoderSessionToken
+// @Accept json
+// @Tags Audit
+// @Param request body codersdk.CreateTestAuditLogRequest true "Audit log request"
+// @Success 204
+// @Router /audit/testgenerate [post]
 func (api *API) generateFakeAuditLog(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	if !api.Authorize(r, rbac.ActionCreate, rbac.ResourceAuditLog) {

diff --git a/coderd/deploymentconfig.go b/coderd/deploymentconfig.go
@@ -7,6 +7,13 @@ import (
 	"github.com/coder/coder/coderd/rbac"
 )
 
+// @Summary Get deployment config
+// @ID get-deployment-config
+// @Security CoderSessionToken
+// @Produce json
+// @Tags General
+// @Success 200 {object} codersdk.DeploymentConfig
+// @Router /config/deployment [get]
 func (api *API) deploymentConfig(rw http.ResponseWriter, r *http.Request) {
 	if !api.Authorize(r, rbac.ActionRead, rbac.ResourceDeploymentConfig) {
 		httpapi.Forbidden(rw)

diff --git a/coderd/files.go b/coderd/files.go
@@ -23,6 +23,17 @@ const (
 	tarMimeType = "application/x-tar"
 )
 
+// @Summary Upload file
+// @Description Notice: Swagger 2.0 doesn't support file upload with a `content-type` different than `application/x-www-form-urlencoded`.
+// @ID update-file
+// @Security CoderSessionToken
+// @Produce json
+// @Accept application/x-tar
+// @Tags Files
+// @Param Content-Type header string true "Content-Type must be `application/x-tar`" default(application/x-tar)
+// @Param file formData file true "File to be uploaded"
+// @Success 201 {object} codersdk.UploadResponse
+// @Router /files [post]
 func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	apiKey := httpmw.APIKey(r)
@@ -88,6 +99,13 @@ func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// @Summary Get file by ID
+// @ID get-file-by-id
+// @Security CoderSessionToken
+// @Tags Files
+// @Param fileID path string true "File ID" format(uuid)
+// @Success 200
+// @Router /files/{fileID} [get]
 func (api *API) fileByID(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

diff --git a/coderd/parameters.go b/coderd/parameters.go
@@ -18,6 +18,17 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Create parameter
+// @ID create-parameter
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Parameters
+// @Param request body codersdk.CreateParameterRequest true "Parameter request"
+// @Param scope path string true "Scope" Enums(template,workspace,import_job)
+// @Param id path string true "ID" format(uuid)
+// @Success 201 {object} codersdk.Parameter
+// @Router /parameters/{scope}/{id} [post]
 func (api *API) postParameter(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	scope, scopeID, valid := readScopeAndID(ctx, rw, r)
@@ -78,6 +89,15 @@ func (api *API) postParameter(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusCreated, convertParameterValue(parameterValue))
 }
 
+// @Summary Get parameters
+// @ID get-parameters
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Parameters
+// @Param scope path string true "Scope" Enums(template,workspace,import_job)
+// @Param id path string true "ID" format(uuid)
+// @Success 200 {array} codersdk.Parameter
+// @Router /parameters/{scope}/{id} [get]
 func (api *API) parameters(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	scope, scopeID, valid := readScopeAndID(ctx, rw, r)
@@ -116,6 +136,16 @@ func (api *API) parameters(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiParameterValues)
 }
 
+// @Summary Delete parameter
+// @ID delete-parameter
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Parameters
+// @Param scope path string true "Scope" Enums(template,workspace,import_job)
+// @Param id path string true "ID" format(uuid)
+// @Param name path string true "Name"
+// @Success 200 {object} codersdk.Response
+// @Router /parameters/{scope}/{id}/{name} [delete]
 func (api *API) deleteParameter(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	scope, scopeID, valid := readScopeAndID(ctx, rw, r)

diff --git a/coderd/templates.go b/coderd/templates.go
@@ -478,7 +478,7 @@ func (api *API) templateByOrganizationAndName(rw http.ResponseWriter, r *http.Re
 // @Tags Templates
 // @Param id path string true "Template ID" format(uuid)
 // @Success 200 {object} codersdk.Template
-// @Router /templates/{id} [get]
+// @Router /templates/{id} [patch]
 func (api *API) patchTemplateMeta(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()

diff --git a/codersdk/audit.go b/codersdk/audit.go
@@ -121,8 +121,8 @@ type AuditLogResponse struct {
 }
 
 type CreateTestAuditLogRequest struct {
-	Action       AuditAction  `json:"action,omitempty"`
-	ResourceType ResourceType `json:"resource_type,omitempty"`
+	Action       AuditAction  `json:"action,omitempty" enums:"create,write,delete,start,stop"`
+	ResourceType ResourceType `json:"resource_type,omitempty" enums:"organization,template,template_version,user,workspace,workspace_build,git_ssh_key,api_key,group"`
 	ResourceID   uuid.UUID    `json:"resource_id,omitempty"`
 	Time         time.Time    `json:"time,omitempty"`
 }

diff --git a/codersdk/parameters.go b/codersdk/parameters.go
@@ -49,13 +49,15 @@ type ComputedParameter struct {
 }
 
 // Parameter represents a set value for the scope.
+//
+// @Description Parameter represents a set value for the scope.
 type Parameter struct {
-	ID                uuid.UUID                  `json:"id" table:"id"`
-	Scope             ParameterScope             `json:"scope" table:"scope"`
-	ScopeID           uuid.UUID                  `json:"scope_id" table:"scope id"`
+	ID                uuid.UUID                  `json:"id" table:"id" format:"uuid"`
+	Scope             ParameterScope             `json:"scope" table:"scope" enums:"template,workspace,import_job"`
+	ScopeID           uuid.UUID                  `json:"scope_id" table:"scope id" format:"uuid"`
 	Name              string                     `json:"name" table:"name"`
-	SourceScheme      ParameterSourceScheme      `json:"source_scheme" table:"source scheme" validate:"ne=none"`
-	DestinationScheme ParameterDestinationScheme `json:"destination_scheme" table:"destination scheme" validate:"ne=none"`
+	SourceScheme      ParameterSourceScheme      `json:"source_scheme" table:"source scheme" validate:"ne=none" enums:"none,data"`
+	DestinationScheme ParameterDestinationScheme `json:"destination_scheme" table:"destination scheme" validate:"ne=none" enums:"none,environment_variable,provisioner_variable"`
 	CreatedAt         time.Time                  `json:"created_at" table:"created at"`
 	UpdatedAt         time.Time                  `json:"updated_at" table:"updated at"`
 }
@@ -96,8 +98,8 @@ type CreateParameterRequest struct {
 
 	Name              string                     `json:"name" validate:"required"`
 	SourceValue       string                     `json:"source_value" validate:"required"`
-	SourceScheme      ParameterSourceScheme      `json:"source_scheme" validate:"oneof=data,required"`
-	DestinationScheme ParameterDestinationScheme `json:"destination_scheme" validate:"oneof=environment_variable provisioner_variable,required"`
+	SourceScheme      ParameterSourceScheme      `json:"source_scheme" validate:"oneof=data,required" enums:"none,data"`
+	DestinationScheme ParameterDestinationScheme `json:"destination_scheme" validate:"oneof=environment_variable provisioner_variable,required" enums:"none,environment_variable,provisioner_variable"`
 }
 
 func (c *Client) CreateParameter(ctx context.Context, scope ParameterScope, id uuid.UUID, req CreateParameterRequest) (Parameter, error) {

diff --git a/codersdk/workspacebuilds.go b/codersdk/workspacebuilds.go
@@ -67,7 +67,7 @@ type WorkspaceBuild struct {
 	Job                 ProvisionerJob      `json:"job"`
 	Reason              BuildReason         `db:"reason" json:"reason"`
 	Resources           []WorkspaceResource `json:"resources"`
-	Deadline            NullTime            `json:"deadline,omitempty"`
+	Deadline            NullTime            `json:"deadline,omitempty" swaggertype:"string" format:"date-time"`
 	Status              WorkspaceStatus     `json:"status" enums:"pending,starting,running,stopping,stopped,failed,canceling,canceled,deleting,deleted"`
 	DailyCost           int32               `json:"daily_cost"`
 }

diff --git a/docs/api/audit.md b/docs/api/audit.md
@@ -0,0 +1,129 @@
+# Audit
+
+> This page is incomplete, stay tuned.
+
+## Get audit logs
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/audit?q=string \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`GET /audit`
+
+### Parameters
+
+| Name       | In    | Type         | Required | Description  |
+| ---------- | ----- | ------------ | -------- | ------------ |
+| `q`        | query | string       | true     | Search query |
+| `after_id` | query | string(uuid) | false    | After ID     |
+| `limit`    | query | integer      | false    | Page limit   |
+| `offset`   | query | integer      | false    | Page offset  |
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "audit_logs": [
+    {
+      "action": "string",
+      "additional_fields": [0],
+      "description": "string",
+      "diff": {
+        "property1": {
+          "new": null,
+          "old": null,
+          "secret": true
+        },
+        "property2": {
+          "new": null,
+          "old": null,
+          "secret": true
+        }
+      },
+      "id": "string",
+      "ip": {},
+      "is_deleted": true,
+      "organization_id": "string",
+      "request_id": "string",
+      "resource_icon": "string",
+      "resource_id": "string",
+      "resource_link": "string",
+      "resource_target": "string",
+      "resource_type": "string",
+      "status_code": 0,
+      "time": "string",
+      "user": {
+        "avatar_url": "string",
+        "created_at": "string",
+        "email": "string",
+        "id": "string",
+        "last_seen_at": "string",
+        "organization_ids": ["string"],
+        "roles": [
+          {
+            "display_name": "string",
+            "name": "string"
+          }
+        ],
+        "status": "string",
+        "username": "string"
+      },
+      "user_agent": "string"
+    }
+  ],
+  "count": 0
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                           |
+| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.AuditLogResponse](schemas.md#codersdkauditlogresponse) |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
+
+## Generate fake audit log
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X POST http://coder-server:8080/api/v2/audit/testgenerate \
+  -H 'Content-Type: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`POST /audit/testgenerate`
+
+> Body parameter
+
+```json
+{
+  "action": "create",
+  "resource_id": "string",
+  "resource_type": "organization",
+  "time": "string"
+}
+```
+
+### Parameters
+
+| Name   | In   | Type                                                                               | Required | Description       |
+| ------ | ---- | ---------------------------------------------------------------------------------- | -------- | ----------------- |
+| `body` | body | [codersdk.CreateTestAuditLogRequest](schemas.md#codersdkcreatetestauditlogrequest) | true     | Audit log request |
+
+### Responses
+
+| Status | Meaning                                                         | Description | Schema |
+| ------ | --------------------------------------------------------------- | ----------- | ------ |
+| 204    | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content  |        |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
diff --git a/docs/api/files.md b/docs/api/files.md
@@ -0,0 +1,77 @@
+# Files
+
+> This page is incomplete, stay tuned.
+
+## Upload file
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X POST http://coder-server:8080/api/v2/files \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/x-tar' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`POST /files`
+
+Notice: Swagger 2.0 doesn't support file upload with a `content-type` different than `application/x-www-form-urlencoded`.
+
+> Body parameter
+
+```yaml
+file: string
+```
+
+### Parameters
+
+| Name           | In     | Type           | Required | Description                              |
+| -------------- | ------ | -------------- | -------- | ---------------------------------------- |
+| `Content-Type` | header | string         | true     | Content-Type must be `application/x-tar` |
+| `body`         | body   | object         | true     |                                          |
+| `» file`       | body   | string(binary) | true     | File to be uploaded                      |
+
+### Example responses
+
+> 201 Response
+
+```json
+{
+  "hash": "string"
+}
+```
+
+### Responses
+
+| Status | Meaning                                                      | Description | Schema                                                       |
+| ------ | ------------------------------------------------------------ | ----------- | ------------------------------------------------------------ |
+| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created     | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
+
+## Get file by ID
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/files/{fileID} \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`GET /files/{fileID}`
+
+### Parameters
+
+| Name     | In   | Type         | Required | Description |
+| -------- | ---- | ------------ | -------- | ----------- |
+| `fileID` | path | string(uuid) | true     | File ID     |
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema |
+| ------ | ------------------------------------------------------- | ----------- | ------ |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          |        |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.