From ffc17487c6934ef077273668d3b9092924ce31c5 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 15:05:20 +0100 Subject: [PATCH 01/28] docs: Applications --- coderd/apidoc/docs.go | 64 ++++++++++++++++++++++++++++++++++++++ coderd/apidoc/swagger.json | 56 +++++++++++++++++++++++++++++++++ coderd/workspaceapps.go | 16 ++++++++++ codersdk/workspaces.go | 1 + docs/api/applications.md | 62 ++++++++++++++++++++++++++++++++++++ docs/api/schemas.md | 14 +++++++++ docs/manifest.json | 4 +++ 7 files changed, 217 insertions(+) create mode 100644 docs/api/applications.md diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index d17ba4bdc057d..191bc2c3e246c 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -25,6 +25,61 @@ const docTemplate = `{ "host": "{{.Host}}", "basePath": "{{.BasePath}}", "paths": { + "/applications/auth-redirect": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Applications" + ], + "summary": "Redirect to URI with encrypted API key", + "operationId": "redirect-to-uri-with-encrypted-api-key", + "parameters": [ + { + "type": "string", + "description": "Redirect destination", + "name": "redirect_uri", + "in": "query" + } + ], + "responses": { + "307": { + "description": "Temporary Redirect" + } + } + } + }, + "/applications/host": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Applications" + ], + "summary": "Get applications host", + "operationId": "get-app-host", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.GetAppHostResponse" + } + } + } + } + }, "/organizations/{organization-id}/templates/": { "post": { "security": [ @@ -712,6 +767,15 @@ const docTemplate = `{ } } }, + "codersdk.GetAppHostResponse": { + "type": "object", + "properties": { + "host": { + "description": "Host is the externally accessible URL for the Coder instance.", + "type": "string" + } + } + }, "codersdk.Healthcheck": { "type": "object", "properties": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index f8dd88c2d167b..65ea8f9918036 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -17,6 +17,53 @@ }, "basePath": "/api/v2", "paths": { + "/applications/auth-redirect": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Applications"], + "summary": "Redirect to URI with encrypted API key", + "operationId": "redirect-to-uri-with-encrypted-api-key", + "parameters": [ + { + "type": "string", + "description": "Redirect destination", + "name": "redirect_uri", + "in": "query" + } + ], + "responses": { + "307": { + "description": "Temporary Redirect" + } + } + } + }, + "/applications/host": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Applications"], + "summary": "Get applications host", + "operationId": "get-app-host", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.GetAppHostResponse" + } + } + } + } + }, "/organizations/{organization-id}/templates/": { "post": { "security": [ @@ -635,6 +682,15 @@ } } }, + "codersdk.GetAppHostResponse": { + "type": "object", + "properties": { + "host": { + "description": "Host is the externally accessible URL for the Coder instance.", + "type": "string" + } + } + }, "codersdk.Healthcheck": { "type": "object", "properties": { diff --git a/coderd/workspaceapps.go b/coderd/workspaceapps.go index 380a02c3b0e73..d3f52fb448390 100644 --- a/coderd/workspaceapps.go +++ b/coderd/workspaceapps.go @@ -56,6 +56,13 @@ var nonCanonicalHeaders = map[string]string{ "Sec-Websocket-Version": "Sec-WebSocket-Version", } +// @Summary Get applications host +// @ID get-app-host +// @Security CoderSessionToken +// @Produce json +// @Tags Applications +// @Success 200 {object} codersdk.GetAppHostResponse +// @Router /applications/host [get] func (api *API) appHost(rw http.ResponseWriter, r *http.Request) { host := api.AppHostname if host != "" && api.AccessURL.Port() != "" { @@ -484,6 +491,15 @@ func (api *API) verifyWorkspaceApplicationSubdomainAuth(rw http.ResponseWriter, return false } +// @Summary Redirect to URI with encrypted API key +// @ID redirect-to-uri-with-encrypted-api-key +// @Security CoderSessionToken +// @Produce json +// @Tags Applications +// @Param redirect_uri query string false "Redirect destination" +// @Success 307 +// @Router /applications/auth-redirect [get] +// // workspaceApplicationAuth is an endpoint on the main router that handles // redirects from the subdomain handler. // diff --git a/codersdk/workspaces.go b/codersdk/workspaces.go index 50a28c42e1a09..75901bc4923ec 100644 --- a/codersdk/workspaces.go +++ b/codersdk/workspaces.go @@ -350,6 +350,7 @@ func (c *Client) WorkspaceByOwnerAndName(ctx context.Context, owner string, name } type GetAppHostResponse struct { + // Host is the externally accessible URL for the Coder instance. Host string `json:"host"` } diff --git a/docs/api/applications.md b/docs/api/applications.md new file mode 100644 index 0000000000000..37e9eec8d5f4e --- /dev/null +++ b/docs/api/applications.md @@ -0,0 +1,62 @@ +# Applications + +> This page is incomplete, stay tuned. + +## Redirect to URI with encrypted API key + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/applications/auth-redirect \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`GET /applications/auth-redirect` + +### Parameters + +| Name | In | Type | Required | Description | +| ------------ | ----- | ------ | -------- | -------------------- | +| redirect_uri | query | string | false | Redirect destination | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ----------------------------------------------------------------------- | ------------------ | --------- | +| 307 | [Temporary Redirect](https://tools.ietf.org/html/rfc7231#section-6.4.7) | Temporary Redirect | no schema | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. + +## Get applications host + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/applications/host \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`GET /applications/host` + +### Example responses + +> 200 Response + +```json +{ + "host": "string" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.GetAppHostResponse](schemas.md#codersdkgetapphostresponse) | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 6b1c5e2bbce3e..9d8be6003d6da 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -84,6 +84,20 @@ | `latency_ms` | number | false | none | none | | `preferred` | boolean | false | none | none | +## codersdk.GetAppHostResponse + +```json +{ + "host": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------ | ------ | -------- | ------------ | ------------------------------------------------------------- | +| `host` | string | false | none | Host is the externally accessible URL for the Coder instance. | + ## codersdk.Healthcheck ```json diff --git a/docs/manifest.json b/docs/manifest.json index 7be313ff7b63d..676c65af39891 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -329,6 +329,10 @@ "title": "Authentication", "path": "./api/authentication.md" }, + { + "title": "Applications", + "path": "./api/applications.md" + }, { "title": "Templates", "path": "./api/templates.md" From d259c0542a337a9a2ea9b8bf6ad34f949e1705b9 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 15:33:27 +0100 Subject: [PATCH 02/28] WIP --- coderd/apidoc/docs.go | 97 +++++++++++++++++++++++++++++++++++-- coderd/apidoc/swagger.json | 86 ++++++++++++++++++++++++++++++++- coderd/authorize.go | 10 ++++ coderd/workspaceapps.go | 1 - codersdk/authorization.go | 8 +-- docs/api/authorization.md | 70 +++++++++++++++++++++++++++ docs/api/schemas.md | 99 ++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 4 ++ 8 files changed, 366 insertions(+), 9 deletions(-) create mode 100644 docs/api/authorization.md diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 191bc2c3e246c..8d9ef73872ae4 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -32,9 +32,6 @@ const docTemplate = `{ "CoderSessionToken": [] } ], - "produces": [ - "application/json" - ], "tags": [ "Applications" ], @@ -80,6 +77,42 @@ const docTemplate = `{ } } }, + "/authcheck": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Authorization" + ], + "summary": "Check authorization", + "operationId": "check-authorization", + "parameters": [ + { + "description": "Authorization request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AuthorizationRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AuthorizationResponse" + } + } + } + } + }, "/organizations/{organization-id}/templates/": { "post": { "security": [ @@ -679,6 +712,64 @@ const docTemplate = `{ } }, "definitions": { + "codersdk.AuthorizationCheck": { + "type": "object", + "properties": { + "action": { + "description": "Action can be ` + "`" + `create` + "`" + `, ` + "`" + `read` + "`" + `, ` + "`" + `update` + "`" + `, or ` + "`" + `delete` + "`" + `", + "type": "string", + "enum": [ + "create", + "read", + "update", + "delete" + ] + }, + "object": { + "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", + "$ref": "#/definitions/codersdk.AuthorizationObject" + } + } + }, + "codersdk.AuthorizationObject": { + "type": "object", + "properties": { + "organization_id": { + "description": "OrganizationID (optional) is an organization_id. It adds the set constraint to\nall resources owned by a given organization.", + "type": "string" + }, + "owner_id": { + "description": "OwnerID (optional) is a user_id. It adds the set constraint to all resources owned\nby a given user.", + "type": "string" + }, + "resource_id": { + "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the 'OwnerID' and 'OrganizationID'\nif possible. Be as specific as possible using all the fields relevant.", + "type": "string" + }, + "resource_type": { + "description": "ResourceType is the name of the resource.\n` + "`" + `./coderd/rbac/object.go` + "`" + ` has the list of valid resource types.", + "type": "string" + } + } + }, + "codersdk.AuthorizationRequest": { + "type": "object", + "properties": { + "checks": { + "description": "Checks is a map keyed with an arbitrary string to a permission check.\nThe key can be any string that is helpful to the caller, and allows\nmultiple permission checks to be run in a single request.\nThe key ensures that each permission check has the same key in the\nresponse.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.AuthorizationCheck" + } + } + } + }, + "codersdk.AuthorizationResponse": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + }, "codersdk.CreateParameterRequest": { "type": "object", "required": [ diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 65ea8f9918036..cb47498a3a0d9 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -24,7 +24,6 @@ "CoderSessionToken": [] } ], - "produces": ["application/json"], "tags": ["Applications"], "summary": "Redirect to URI with encrypted API key", "operationId": "redirect-to-uri-with-encrypted-api-key", @@ -64,6 +63,38 @@ } } }, + "/authcheck": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Authorization"], + "summary": "Check authorization", + "operationId": "check-authorization", + "parameters": [ + { + "description": "Authorization request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AuthorizationRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AuthorizationResponse" + } + } + } + } + }, "/organizations/{organization-id}/templates/": { "post": { "security": [ @@ -602,6 +633,59 @@ } }, "definitions": { + "codersdk.AuthorizationCheck": { + "type": "object", + "properties": { + "action": { + "description": "Action can be `create`, `read`, `update`, or `delete`", + "type": "string", + "enum": ["create", "read", "update", "delete"] + }, + "object": { + "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", + "$ref": "#/definitions/codersdk.AuthorizationObject" + } + } + }, + "codersdk.AuthorizationObject": { + "type": "object", + "properties": { + "organization_id": { + "description": "OrganizationID (optional) is an organization_id. It adds the set constraint to\nall resources owned by a given organization.", + "type": "string" + }, + "owner_id": { + "description": "OwnerID (optional) is a user_id. It adds the set constraint to all resources owned\nby a given user.", + "type": "string" + }, + "resource_id": { + "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the 'OwnerID' and 'OrganizationID'\nif possible. Be as specific as possible using all the fields relevant.", + "type": "string" + }, + "resource_type": { + "description": "ResourceType is the name of the resource.\n`./coderd/rbac/object.go` has the list of valid resource types.", + "type": "string" + } + } + }, + "codersdk.AuthorizationRequest": { + "type": "object", + "properties": { + "checks": { + "description": "Checks is a map keyed with an arbitrary string to a permission check.\nThe key can be any string that is helpful to the caller, and allows\nmultiple permission checks to be run in a single request.\nThe key ensures that each permission check has the same key in the\nresponse.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.AuthorizationCheck" + } + } + } + }, + "codersdk.AuthorizationResponse": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + }, "codersdk.CreateParameterRequest": { "type": "object", "required": [ diff --git a/coderd/authorize.go b/coderd/authorize.go index d2bded638e163..73a46e2328ec2 100644 --- a/coderd/authorize.go +++ b/coderd/authorize.go @@ -104,6 +104,16 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action, return prepared, nil } +// @Summary Check authorization +// @ID check-authorization +// @Security CoderSessionToken +// @Consume json +// @Produce json +// @Tags Authorization +// @Param request body codersdk.AuthorizationRequest true "Authorization request" +// @Success 200 {object} codersdk.AuthorizationResponse +// @Router /authcheck [post] +// // checkAuthorization returns if the current API key can use the given // permissions, factoring in the current user's roles and the API key scopes. func (api *API) checkAuthorization(rw http.ResponseWriter, r *http.Request) { diff --git a/coderd/workspaceapps.go b/coderd/workspaceapps.go index d3f52fb448390..5b394b7811d20 100644 --- a/coderd/workspaceapps.go +++ b/coderd/workspaceapps.go @@ -494,7 +494,6 @@ func (api *API) verifyWorkspaceApplicationSubdomainAuth(rw http.ResponseWriter, // @Summary Redirect to URI with encrypted API key // @ID redirect-to-uri-with-encrypted-api-key // @Security CoderSessionToken -// @Produce json // @Tags Applications // @Param redirect_uri query string false "Redirect destination" // @Success 307 diff --git a/codersdk/authorization.go b/codersdk/authorization.go index edf24c64f4431..8f3cf59ca5c4c 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -10,7 +10,7 @@ type AuthorizationResponse map[string]bool // AuthorizationRequest is a structure instead of a map because // go-playground/validate can only validate structs. If you attempt to pass -// a map into 'httpapi.Read', you will get an invalid type error. +// a map into `httpapi.Read`, you will get an invalid type error. type AuthorizationRequest struct { // Checks is a map keyed with an arbitrary string to a permission check. // The key can be any string that is helpful to the caller, and allows @@ -34,13 +34,13 @@ type AuthorizationCheck struct { // Omitting the 'OrganizationID' could produce the incorrect value, as // workspaces have both `user` and `organization` owners. Object AuthorizationObject `json:"object"` - // Action can be 'create', 'read', 'update', or 'delete' - Action string `json:"action"` + // Action can be `create`, `read`, `update`, or `delete` + Action string `json:"action" enums:"create,read,update,delete"` } type AuthorizationObject struct { // ResourceType is the name of the resource. - // './coderd/rbac/object.go' has the list of valid resource types. + // `./coderd/rbac/object.go` has the list of valid resource types. ResourceType string `json:"resource_type"` // OwnerID (optional) is a user_id. It adds the set constraint to all resources owned // by a given user. diff --git a/docs/api/authorization.md b/docs/api/authorization.md new file mode 100644 index 0000000000000..c9cc3ee885df7 --- /dev/null +++ b/docs/api/authorization.md @@ -0,0 +1,70 @@ +# Authorization + +> This page is incomplete, stay tuned. + +## Check authorization + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/authcheck \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`POST /authcheck` + +> Body parameter + +```json +{ + "checks": { + "property1": { + "action": "create", + "object": { + "organization_id": "string", + "owner_id": "string", + "resource_id": "string", + "resource_type": "string" + } + }, + "property2": { + "action": "create", + "object": { + "organization_id": "string", + "owner_id": "string", + "resource_id": "string", + "resource_type": "string" + } + } + } +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ---- | ---- | ------------------------------------------------------------------------ | -------- | --------------------- | +| body | body | [codersdk.AuthorizationRequest](schemas.md#codersdkauthorizationrequest) | true | Authorization request | + +### Example responses + +> 200 Response + +```json +{ + "property1": true, + "property2": true +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AuthorizationResponse](schemas.md#codersdkauthorizationresponse) | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 9d8be6003d6da..dddcb21a42c3c 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -2,6 +2,105 @@ > This page is incomplete, stay tuned. +## codersdk.AuthorizationCheck + +```json +{ + "action": "create", + "object": { + "organization_id": "string", + "owner_id": "string", + "resource_id": "string", + "resource_type": "string" + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| -------- | ------------------------------------------------------------ | -------- | ------------ | ----------------------------------------------------- | +| `action` | string | false | none | Action can be `create`, `read`, `update`, or `delete` | +| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | none | none | + +#### Enumerated Values + +| Property | Value | +| -------- | ------ | +| action | create | +| action | read | +| action | update | +| action | delete | + +## codersdk.AuthorizationObject + +```json +{ + "organization_id": "string", + "owner_id": "string", + "resource_id": "string", + "resource_type": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization_id` | string | false | none | Organization id (optional) is an organization_id. It adds the set constraint to
all resources owned by a given organization. | +| `owner_id` | string | false | none | Owner id (optional) is a user_id. It adds the set constraint to all resources owned
by a given user. | +| `resource_id` | string | false | none | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the 'OwnerID' and 'OrganizationID'
if possible. Be as specific as possible using all the fields relevant. | +| `resource_type` | string | false | none | Resource type is the name of the resource.
`./coderd/rbac/object.go` has the list of valid resource types. | + +## codersdk.AuthorizationRequest + +```json +{ + "checks": { + "property1": { + "action": "create", + "object": { + "organization_id": "string", + "owner_id": "string", + "resource_id": "string", + "resource_type": "string" + } + }, + "property2": { + "action": "create", + "object": { + "organization_id": "string", + "owner_id": "string", + "resource_id": "string", + "resource_type": "string" + } + } + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `checks` | object | false | none | Checks is a map keyed with an arbitrary string to a permission check.
The key can be any string that is helpful to the caller, and allows
multiple permission checks to be run in a single request.
The key ensures that each permission check has the same key in the
response. | +| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | none | none | + +## codersdk.AuthorizationResponse + +```json +{ + "property1": true, + "property2": true +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------------- | ------- | -------- | ------------ | ----------- | +| `[any property]` | boolean | false | none | none | + ## codersdk.CreateParameterRequest ```json diff --git a/docs/manifest.json b/docs/manifest.json index 676c65af39891..b635e8a1f8688 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -333,6 +333,10 @@ "title": "Applications", "path": "./api/applications.md" }, + { + "title": "Authorization", + "path": "./api/authorization.md" + }, { "title": "Templates", "path": "./api/templates.md" From a26eac54d46ecf6de2aeebda312a0cdaf0640f17 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 15:44:53 +0100 Subject: [PATCH 03/28] WIP --- coderd/apidoc/docs.go | 8 ++++---- coderd/apidoc/swagger.json | 8 ++++---- codersdk/authorization.go | 25 ++++++++++--------------- docs/api/schemas.md | 6 +++--- 4 files changed, 21 insertions(+), 26 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 8d9ef73872ae4..01a3f1f82cd8c 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -726,7 +726,7 @@ const docTemplate = `{ ] }, "object": { - "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", + "description": "Object can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } @@ -735,15 +735,15 @@ const docTemplate = `{ "type": "object", "properties": { "organization_id": { - "description": "OrganizationID (optional) is an organization_id. It adds the set constraint to\nall resources owned by a given organization.", + "description": "Organization ID (optional) adds the set constraint to all resources owned by a given organization.", "type": "string" }, "owner_id": { - "description": "OwnerID (optional) is a user_id. It adds the set constraint to all resources owned\nby a given user.", + "description": "OwnerID (optional) adds the set constraint to all resources owned by a given user.", "type": "string" }, "resource_id": { - "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the 'OwnerID' and 'OrganizationID'\nif possible. Be as specific as possible using all the fields relevant.", + "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the ` + "`" + `OwnerID` + "`" + ` and ` + "`" + `OrganizationID` + "`" + `\nif possible. Be as specific as possible using all the fields relevant.", "type": "string" }, "resource_type": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index cb47498a3a0d9..a36452a328f05 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -642,7 +642,7 @@ "enum": ["create", "read", "update", "delete"] }, "object": { - "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", + "description": "Object can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } @@ -651,15 +651,15 @@ "type": "object", "properties": { "organization_id": { - "description": "OrganizationID (optional) is an organization_id. It adds the set constraint to\nall resources owned by a given organization.", + "description": "Organization ID (optional) adds the set constraint to all resources owned by a given organization.", "type": "string" }, "owner_id": { - "description": "OwnerID (optional) is a user_id. It adds the set constraint to all resources owned\nby a given user.", + "description": "OwnerID (optional) adds the set constraint to all resources owned by a given user.", "type": "string" }, "resource_id": { - "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the 'OwnerID' and 'OrganizationID'\nif possible. Be as specific as possible using all the fields relevant.", + "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the `OwnerID` and `OrganizationID`\nif possible. Be as specific as possible using all the fields relevant.", "type": "string" }, "resource_type": { diff --git a/codersdk/authorization.go b/codersdk/authorization.go index 8f3cf59ca5c4c..f8faa3d5b24dd 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -23,35 +23,30 @@ type AuthorizationRequest struct { // AuthorizationCheck is used to check if the currently authenticated user (or // the specified user) can do a given action to a given set of objects. type AuthorizationCheck struct { - // Object can represent a "set" of objects, such as: - // - All workspaces in an organization - // - All workspaces owned by me - // - All workspaces across the entire product - // When defining an object, use the most specific language when possible to - // produce the smallest set. Meaning to set as many fields on 'Object' as - // you can. Example, if you want to check if you can update all workspaces - // owned by 'me', try to also add an 'OrganizationID' to the settings. - // Omitting the 'OrganizationID' could produce the incorrect value, as - // workspaces have both `user` and `organization` owners. + // Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. Object AuthorizationObject `json:"object"` // Action can be `create`, `read`, `update`, or `delete` Action string `json:"action" enums:"create,read,update,delete"` } +// AuthorizationObject: when defining, use the most specific language when possible to +// produce the smallest set. Meaning to set as many fields on `Object` as +// you can. Example, if you want to check if you can update all workspaces +// owned by `me`, try to also add an `OrganizationID` to the settings. +// Omitting the `OrganizationID` could produce the incorrect value, as +// workspaces have both `user` and `organization` owners. type AuthorizationObject struct { // ResourceType is the name of the resource. // `./coderd/rbac/object.go` has the list of valid resource types. ResourceType string `json:"resource_type"` - // OwnerID (optional) is a user_id. It adds the set constraint to all resources owned - // by a given user. + // OwnerID (optional) adds the set constraint to all resources owned by a given user. OwnerID string `json:"owner_id,omitempty"` - // OrganizationID (optional) is an organization_id. It adds the set constraint to - // all resources owned by a given organization. + // Organization ID (optional) adds the set constraint to all resources owned by a given organization. OrganizationID string `json:"organization_id,omitempty"` // ResourceID (optional) reduces the set to a singular resource. This assigns // a resource ID to the resource type, eg: a single workspace. // The rbac library will not fetch the resource from the database, so if you - // are using this option, you should also set the 'OwnerID' and 'OrganizationID' + // are using this option, you should also set the `OwnerID` and `OrganizationID` // if possible. Be as specific as possible using all the fields relevant. ResourceID string `json:"resource_id,omitempty"` } diff --git a/docs/api/schemas.md b/docs/api/schemas.md index dddcb21a42c3c..8ef41f5cbf650 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -47,9 +47,9 @@ | Name | Type | Required | Restrictions | Description | | ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organization_id` | string | false | none | Organization id (optional) is an organization_id. It adds the set constraint to
all resources owned by a given organization. | -| `owner_id` | string | false | none | Owner id (optional) is a user_id. It adds the set constraint to all resources owned
by a given user. | -| `resource_id` | string | false | none | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the 'OwnerID' and 'OrganizationID'
if possible. Be as specific as possible using all the fields relevant. | +| `organization_id` | string | false | none | Organization ID (optional) adds the set constraint to all resources owned by a given organization. | +| `owner_id` | string | false | none | Owner id (optional) adds the set constraint to all resources owned by a given user. | +| `resource_id` | string | false | none | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the `OwnerID` and `OrganizationID`
if possible. Be as specific as possible using all the fields relevant. | | `resource_type` | string | false | none | Resource type is the name of the resource.
`./coderd/rbac/object.go` has the list of valid resource types. | ## codersdk.AuthorizationRequest From 9950d35b41ecc8a6856818dc747be03b83b6964f Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 17:42:20 +0100 Subject: [PATCH 04/28] WIP --- coderd/apidoc/docs.go | 3 +-- coderd/apidoc/swagger.json | 3 +-- codersdk/authorization.go | 20 +++++++++++--------- docs/api/schemas.md | 8 ++++---- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 01a3f1f82cd8c..63290cc261052 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -716,7 +716,6 @@ const docTemplate = `{ "type": "object", "properties": { "action": { - "description": "Action can be ` + "`" + `create` + "`" + `, ` + "`" + `read` + "`" + `, ` + "`" + `update` + "`" + `, or ` + "`" + `delete` + "`" + `", "type": "string", "enum": [ "create", @@ -726,7 +725,7 @@ const docTemplate = `{ ] }, "object": { - "description": "Object can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.", + "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index a36452a328f05..225492d5d1a2d 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -637,12 +637,11 @@ "type": "object", "properties": { "action": { - "description": "Action can be `create`, `read`, `update`, or `delete`", "type": "string", "enum": ["create", "read", "update", "delete"] }, "object": { - "description": "Object can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.", + "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } diff --git a/codersdk/authorization.go b/codersdk/authorization.go index f8faa3d5b24dd..5787eb580d10d 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -23,18 +23,20 @@ type AuthorizationRequest struct { // AuthorizationCheck is used to check if the currently authenticated user (or // the specified user) can do a given action to a given set of objects. type AuthorizationCheck struct { - // Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. + // Object can represent a "set" of objects, such as: + // - All workspaces in an organization + // - All workspaces owned by me + // - All workspaces across the entire product + // When defining an object, use the most specific language when possible to + // produce the smallest set. Meaning to set as many fields on 'Object' as + // you can. Example, if you want to check if you can update all workspaces + // owned by 'me', try to also add an 'OrganizationID' to the settings. + // Omitting the 'OrganizationID' could produce the incorrect value, as + // workspaces have both `user` and `organization` owners. Object AuthorizationObject `json:"object"` - // Action can be `create`, `read`, `update`, or `delete` - Action string `json:"action" enums:"create,read,update,delete"` + Action string `json:"action" enums:"create,read,update,delete"` } -// AuthorizationObject: when defining, use the most specific language when possible to -// produce the smallest set. Meaning to set as many fields on `Object` as -// you can. Example, if you want to check if you can update all workspaces -// owned by `me`, try to also add an `OrganizationID` to the settings. -// Omitting the `OrganizationID` could produce the incorrect value, as -// workspaces have both `user` and `organization` owners. type AuthorizationObject struct { // ResourceType is the name of the resource. // `./coderd/rbac/object.go` has the list of valid resource types. diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 8ef41f5cbf650..34fc584c43e59 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -18,10 +18,10 @@ ### Properties -| Name | Type | Required | Restrictions | Description | -| -------- | ------------------------------------------------------------ | -------- | ------------ | ----------------------------------------------------- | -| `action` | string | false | none | Action can be `create`, `read`, `update`, or `delete` | -| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | none | none | +| Name | Type | Required | Restrictions | Description | +| -------- | ------------------------------------------------------------ | -------- | ------------ | ----------- | +| `action` | string | false | none | none | +| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | none | none | #### Enumerated Values From fbbbf9a7e3de76675543a73a6c098bc851c2417c Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 18:54:20 +0100 Subject: [PATCH 05/28] Fix: consume --- coderd/apidoc/docs.go | 20 +++++++++++++++++++- coderd/apidoc/swagger.json | 8 +++++++- coderd/authorize.go | 2 +- coderd/templates.go | 2 +- coderd/workspaces.go | 8 ++++---- codersdk/authorization.go | 7 ++++--- 6 files changed, 36 insertions(+), 11 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 63290cc261052..846628306489e 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -84,6 +84,9 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], @@ -120,6 +123,9 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], @@ -515,6 +521,9 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], @@ -556,6 +565,9 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], @@ -597,6 +609,9 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], @@ -641,6 +656,9 @@ const docTemplate = `{ "CoderSessionToken": [] } ], + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], @@ -725,7 +743,7 @@ const docTemplate = `{ ] }, "object": { - "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", + "description": "Object can represent a \"set\" of objects, such as:\n- All workspaces in an organization\n- All workspaces owned by me\n- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 225492d5d1a2d..8b433313c68de 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -70,6 +70,7 @@ "CoderSessionToken": [] } ], + "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Authorization"], "summary": "Check authorization", @@ -102,6 +103,7 @@ "CoderSessionToken": [] } ], + "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Templates"], "summary": "Create template by organization", @@ -456,6 +458,7 @@ "CoderSessionToken": [] } ], + "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Workspaces"], "summary": "Update workspace metadata by ID", @@ -493,6 +496,7 @@ "CoderSessionToken": [] } ], + "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Workspaces"], "summary": "Update workspace autostart schedule by ID", @@ -530,6 +534,7 @@ "CoderSessionToken": [] } ], + "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Workspaces"], "summary": "Extend workspace deadline by ID", @@ -570,6 +575,7 @@ "CoderSessionToken": [] } ], + "consumes": ["application/json"], "produces": ["application/json"], "tags": ["Workspaces"], "summary": "Update workspace TTL by ID", @@ -641,7 +647,7 @@ "enum": ["create", "read", "update", "delete"] }, "object": { - "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", + "description": "Object can represent a \"set\" of objects, such as:\n- All workspaces in an organization\n- All workspaces owned by me\n- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } diff --git a/coderd/authorize.go b/coderd/authorize.go index 73a46e2328ec2..6f5a5f63e1a9e 100644 --- a/coderd/authorize.go +++ b/coderd/authorize.go @@ -107,7 +107,7 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action, // @Summary Check authorization // @ID check-authorization // @Security CoderSessionToken -// @Consume json +// @Accept json // @Produce json // @Tags Authorization // @Param request body codersdk.AuthorizationRequest true "Authorization request" diff --git a/coderd/templates.go b/coderd/templates.go index 3cdd437604fd2..74e3560703131 100644 --- a/coderd/templates.go +++ b/coderd/templates.go @@ -145,7 +145,7 @@ func (api *API) deleteTemplate(rw http.ResponseWriter, r *http.Request) { // @Summary Create template by organization // @ID create-template-by-organization // @Security CoderSessionToken -// @Consume json +// @Accept json // @Produce json // @Tags Templates // @Param request body codersdk.CreateTemplateRequest true "Request body" diff --git a/coderd/workspaces.go b/coderd/workspaces.go index 63f0868bcf0f3..23e605b298de1 100644 --- a/coderd/workspaces.go +++ b/coderd/workspaces.go @@ -564,7 +564,7 @@ func (api *API) postWorkspacesByOrganization(rw http.ResponseWriter, r *http.Req // @Summary Update workspace metadata by ID // @ID update-workspace-metadata-by-id // @Security CoderSessionToken -// @Consume json +// @Accept json // @Produce json // @Tags Workspaces // @Param workspace path string true "Workspace ID" format(uuid) @@ -654,7 +654,7 @@ func (api *API) patchWorkspace(rw http.ResponseWriter, r *http.Request) { // @Summary Update workspace autostart schedule by ID // @ID update-workspace-autostart-schedule-by-id // @Security CoderSessionToken -// @Consume json +// @Accept json // @Produce json // @Tags Workspaces // @Param workspace path string true "Workspace ID" format(uuid) @@ -717,7 +717,7 @@ func (api *API) putWorkspaceAutostart(rw http.ResponseWriter, r *http.Request) { // @Summary Update workspace TTL by ID // @ID update-workspace-ttl-by-id // @Security CoderSessionToken -// @Consume json +// @Accept json // @Produce json // @Tags Workspaces // @Param workspace path string true "Workspace ID" format(uuid) @@ -793,7 +793,7 @@ func (api *API) putWorkspaceTTL(rw http.ResponseWriter, r *http.Request) { // @Summary Extend workspace deadline by ID // @ID extend-workspace-deadline-by-id // @Security CoderSessionToken -// @Consume json +// @Accept json // @Produce json // @Tags Workspaces // @Param workspace path string true "Workspace ID" format(uuid) diff --git a/codersdk/authorization.go b/codersdk/authorization.go index 5787eb580d10d..cade92c9c577d 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -24,9 +24,9 @@ type AuthorizationRequest struct { // the specified user) can do a given action to a given set of objects. type AuthorizationCheck struct { // Object can represent a "set" of objects, such as: - // - All workspaces in an organization - // - All workspaces owned by me - // - All workspaces across the entire product + // - All workspaces in an organization + // - All workspaces owned by me + // - All workspaces across the entire product // When defining an object, use the most specific language when possible to // produce the smallest set. Meaning to set as many fields on 'Object' as // you can. Example, if you want to check if you can update all workspaces @@ -37,6 +37,7 @@ type AuthorizationCheck struct { Action string `json:"action" enums:"create,read,update,delete"` } +// AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. type AuthorizationObject struct { // ResourceType is the name of the resource. // `./coderd/rbac/object.go` has the list of valid resource types. From 2f0b499e0a07a6a95eeba5c9eb8fe4df9f89444a Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 19:27:06 +0100 Subject: [PATCH 06/28] Fix: @Description --- coderd/apidoc/docs.go | 4 +++- coderd/apidoc/swagger.json | 4 +++- codersdk/authorization.go | 9 +++++---- docs/api/schemas.md | 16 ++++++++++------ 4 files changed, 21 insertions(+), 12 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 846628306489e..db8dd686ce925 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -731,6 +731,7 @@ const docTemplate = `{ }, "definitions": { "codersdk.AuthorizationCheck": { + "description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.", "type": "object", "properties": { "action": { @@ -749,10 +750,11 @@ const docTemplate = `{ } }, "codersdk.AuthorizationObject": { + "description": "AuthorizationObject can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.", "type": "object", "properties": { "organization_id": { - "description": "Organization ID (optional) adds the set constraint to all resources owned by a given organization.", + "description": "OrganizationID (optional) adds the set constraint to all resources owned by a given organization.", "type": "string" }, "owner_id": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 8b433313c68de..dc8428ae44f24 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -640,6 +640,7 @@ }, "definitions": { "codersdk.AuthorizationCheck": { + "description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.", "type": "object", "properties": { "action": { @@ -653,10 +654,11 @@ } }, "codersdk.AuthorizationObject": { + "description": "AuthorizationObject can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.", "type": "object", "properties": { "organization_id": { - "description": "Organization ID (optional) adds the set constraint to all resources owned by a given organization.", + "description": "OrganizationID (optional) adds the set constraint to all resources owned by a given organization.", "type": "string" }, "owner_id": { diff --git a/codersdk/authorization.go b/codersdk/authorization.go index cade92c9c577d..4d4f1f13924bf 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -20,8 +20,8 @@ type AuthorizationRequest struct { Checks map[string]AuthorizationCheck `json:"checks"` } -// AuthorizationCheck is used to check if the currently authenticated user (or -// the specified user) can do a given action to a given set of objects. +// @Description AuthorizationCheck is used to check if the currently authenticated user (or +// @Description the specified user) can do a given action to a given set of objects. type AuthorizationCheck struct { // Object can represent a "set" of objects, such as: // - All workspaces in an organization @@ -37,14 +37,15 @@ type AuthorizationCheck struct { Action string `json:"action" enums:"create,read,update,delete"` } -// AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. +// @Description AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, +// @Description all workspaces across the entire product. type AuthorizationObject struct { // ResourceType is the name of the resource. // `./coderd/rbac/object.go` has the list of valid resource types. ResourceType string `json:"resource_type"` // OwnerID (optional) adds the set constraint to all resources owned by a given user. OwnerID string `json:"owner_id,omitempty"` - // Organization ID (optional) adds the set constraint to all resources owned by a given organization. + // OrganizationID (optional) adds the set constraint to all resources owned by a given organization. OrganizationID string `json:"organization_id,omitempty"` // ResourceID (optional) reduces the set to a singular resource. This assigns // a resource ID to the resource type, eg: a single workspace. diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 34fc584c43e59..c2caf4af83454 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -16,12 +16,14 @@ } ``` +AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. + ### Properties -| Name | Type | Required | Restrictions | Description | -| -------- | ------------------------------------------------------------ | -------- | ------------ | ----------- | -| `action` | string | false | none | none | -| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | none | none | +| Name | Type | Required | Restrictions | Description | +| -------- | ------------------------------------------------------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `action` | string | false | none | none | +| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | none | Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. | #### Enumerated Values @@ -43,11 +45,13 @@ } ``` +AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. + ### Properties | Name | Type | Required | Restrictions | Description | | ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organization_id` | string | false | none | Organization ID (optional) adds the set constraint to all resources owned by a given organization. | +| `organization_id` | string | false | none | Organization id (optional) adds the set constraint to all resources owned by a given organization. | | `owner_id` | string | false | none | Owner id (optional) adds the set constraint to all resources owned by a given user. | | `resource_id` | string | false | none | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the `OwnerID` and `OrganizationID`
if possible. Be as specific as possible using all the fields relevant. | | `resource_type` | string | false | none | Resource type is the name of the resource.
`./coderd/rbac/object.go` has the list of valid resource types. | @@ -84,7 +88,7 @@ | Name | Type | Required | Restrictions | Description | | ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `checks` | object | false | none | Checks is a map keyed with an arbitrary string to a permission check.
The key can be any string that is helpful to the caller, and allows
multiple permission checks to be run in a single request.
The key ensures that each permission check has the same key in the
response. | -| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | none | none | +| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | none | » **additionalproperties** is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | ## codersdk.AuthorizationResponse From e5a46184ef809975fd87d0cea6829234db99ad66 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Tue, 20 Dec 2022 19:32:33 +0100 Subject: [PATCH 07/28] Fix --- coderd/apidoc/docs.go | 1 + coderd/apidoc/swagger.json | 1 + codersdk/parameters.go | 2 +- docs/api/schemas.md | 4 +++- 4 files changed, 6 insertions(+), 2 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index db8dd686ce925..6d4383dd24540 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -790,6 +790,7 @@ const docTemplate = `{ } }, "codersdk.CreateParameterRequest": { + "description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.", "type": "object", "required": [ "destination_scheme", diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index dc8428ae44f24..8a110fd248a99 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -694,6 +694,7 @@ } }, "codersdk.CreateParameterRequest": { + "description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.", "type": "object", "required": [ "destination_scheme", diff --git a/codersdk/parameters.go b/codersdk/parameters.go index 20184622ddd34..de8f86d4b1bc0 100644 --- a/codersdk/parameters.go +++ b/codersdk/parameters.go @@ -83,7 +83,7 @@ type ParameterSchema struct { ValidationContains []string `json:"validation_contains,omitempty"` } -// CreateParameterRequest is used to create a new parameter value for a scope. +// @Description CreateParameterRequest is a structure used to create a new parameter value for a scope. type CreateParameterRequest struct { // CloneID allows copying the value of another parameter. // The other param must be related to the same template_id for this to diff --git a/docs/api/schemas.md b/docs/api/schemas.md index c2caf4af83454..2e9a9c0f57998 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -117,6 +117,8 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in } ``` +CreateParameterRequest is a structure used to create a new parameter value for a scope. + ### Properties | Name | Type | Required | Restrictions | Description | @@ -168,7 +170,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `display_name` | string | false | none | Display name is the displayed name of the template. | | `icon` | string | false | none | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | | `name` | string | true | none | Name is the name of the template. | -| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | none | none | +| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | none | Parameter values is a structure used to create a new parameter value for a scope.] | | `template_version_id` | string | true | none | Template version id is an in-progress or completed job to use as an initial version
of the template.

This is required on creation to enable a user-flow of validating a
template works. There is no reason the data-model cannot support empty
templates, but it doesn't make sense for users. | ## codersdk.DERPRegion From 15fea1e99adf9ea0a12007f6ad66cbf381a9c2e5 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 09:49:59 +0100 Subject: [PATCH 08/28] docs: apiroot, buildinfo, csp --- coderd/apidoc/docs.go | 108 ++++++++++++++++++++++++++++++++++++ coderd/apidoc/swagger.json | 94 +++++++++++++++++++++++++++++++ coderd/apiroot.go | 22 ++++++++ coderd/buildinfo.go | 23 ++++++++ coderd/coderd.go | 20 +------ coderd/csp.go | 10 ++++ docs/api/general.md | 111 +++++++++++++++++++++++++++++++++++++ docs/api/schemas.md | 30 ++++++++++ docs/manifest.json | 4 ++ 9 files changed, 405 insertions(+), 17 deletions(-) create mode 100644 coderd/apiroot.go create mode 100644 coderd/buildinfo.go create mode 100644 docs/api/general.md diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 6d4383dd24540..0f1464ad5d0d2 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -25,6 +25,31 @@ const docTemplate = `{ "host": "{{.Host}}", "basePath": "{{.BasePath}}", "paths": { + "/": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "General" + ], + "summary": "API root handler", + "operationId": "api-root-handler", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, "/applications/auth-redirect": { "get": { "security": [ @@ -116,6 +141,67 @@ const docTemplate = `{ } } }, + "/buildinfo": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "General" + ], + "summary": "Build info", + "operationId": "build-info", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.BuildInfoResponse" + } + } + } + } + }, + "/csp/reports": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "text/plain" + ], + "tags": [ + "General" + ], + "summary": "Report CSP violations", + "operationId": "report-csp-violations", + "parameters": [ + { + "description": "Violation report", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.cspViolation" + } + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + }, "/organizations/{organization-id}/templates/": { "post": { "security": [ @@ -730,6 +816,15 @@ const docTemplate = `{ } }, "definitions": { + "coderd.cspViolation": { + "type": "object", + "properties": { + "csp-report": { + "type": "object", + "additionalProperties": true + } + } + }, "codersdk.AuthorizationCheck": { "description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.", "type": "object", @@ -789,6 +884,19 @@ const docTemplate = `{ "type": "boolean" } }, + "codersdk.BuildInfoResponse": { + "type": "object", + "properties": { + "external_url": { + "description": "ExternalURL is a URL referencing the current Coder version. For production\nbuilds, this will link directly to a release. For development builds, this\nwill link to a commit.", + "type": "string" + }, + "version": { + "description": "Version returns the semantic version of the build.", + "type": "string" + } + } + }, "codersdk.CreateParameterRequest": { "description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.", "type": "object", diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 8a110fd248a99..2d925361e2f80 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -17,6 +17,27 @@ }, "basePath": "/api/v2", "paths": { + "/": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["General"], + "summary": "API root handler", + "operationId": "api-root-handler", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, "/applications/auth-redirect": { "get": { "security": [ @@ -96,6 +117,57 @@ } } }, + "/buildinfo": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["General"], + "summary": "Build info", + "operationId": "build-info", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.BuildInfoResponse" + } + } + } + } + }, + "/csp/reports": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": ["application/json"], + "produces": ["text/plain"], + "tags": ["General"], + "summary": "Report CSP violations", + "operationId": "report-csp-violations", + "parameters": [ + { + "description": "Violation report", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.cspViolation" + } + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + }, "/organizations/{organization-id}/templates/": { "post": { "security": [ @@ -639,6 +711,15 @@ } }, "definitions": { + "coderd.cspViolation": { + "type": "object", + "properties": { + "csp-report": { + "type": "object", + "additionalProperties": true + } + } + }, "codersdk.AuthorizationCheck": { "description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.", "type": "object", @@ -693,6 +774,19 @@ "type": "boolean" } }, + "codersdk.BuildInfoResponse": { + "type": "object", + "properties": { + "external_url": { + "description": "ExternalURL is a URL referencing the current Coder version. For production\nbuilds, this will link directly to a release. For development builds, this\nwill link to a commit.", + "type": "string" + }, + "version": { + "description": "Version returns the semantic version of the build.", + "type": "string" + } + } + }, "codersdk.CreateParameterRequest": { "description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.", "type": "object", diff --git a/coderd/apiroot.go b/coderd/apiroot.go new file mode 100644 index 0000000000000..29c43a4eba544 --- /dev/null +++ b/coderd/apiroot.go @@ -0,0 +1,22 @@ +package coderd + +import ( + "net/http" + + "github.com/coder/coder/coderd/httpapi" + "github.com/coder/coder/codersdk" +) + +// @Summary API root handler +// @ID api-root-handler +// @Security CoderSessionToken +// @Produce json +// @Tags General +// @Success 200 {object} codersdk.Response +// @Router / [get] +func apiRoot(w http.ResponseWriter, r *http.Request) { + httpapi.Write(r.Context(), w, http.StatusOK, codersdk.Response{ + //nolint:gocritic + Message: "👋", + }) +} diff --git a/coderd/buildinfo.go b/coderd/buildinfo.go new file mode 100644 index 0000000000000..4c592abedcac8 --- /dev/null +++ b/coderd/buildinfo.go @@ -0,0 +1,23 @@ +package coderd + +import ( + "net/http" + + "github.com/coder/coder/buildinfo" + "github.com/coder/coder/coderd/httpapi" + "github.com/coder/coder/codersdk" +) + +// @Summary Build info +// @ID build-info +// @Security CoderSessionToken +// @Produce json +// @Tags General +// @Success 200 {object} codersdk.BuildInfoResponse +// @Router /buildinfo [post] +func buildInfo(rw http.ResponseWriter, r *http.Request) { + httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.BuildInfoResponse{ + ExternalURL: buildinfo.ExternalURL(), + Version: buildinfo.Version(), + }) +} diff --git a/coderd/coderd.go b/coderd/coderd.go index d822fe7ea2573..f66bd82aa630b 100644 --- a/coderd/coderd.go +++ b/coderd/coderd.go @@ -319,26 +319,12 @@ func New(options *Options) *API { // Specific routes can specify smaller limits. httpmw.RateLimit(options.APIRateLimit, time.Minute), ) - r.Get("/", func(w http.ResponseWriter, r *http.Request) { - httpapi.Write(r.Context(), w, http.StatusOK, codersdk.Response{ - //nolint:gocritic - Message: "👋", - }) - }) + r.Get("/", apiRoot) // All CSP errors will be logged r.Post("/csp/reports", api.logReportCSPViolations) - r.Route("/buildinfo", func(r chi.Router) { - r.Get("/", func(rw http.ResponseWriter, r *http.Request) { - httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.BuildInfoResponse{ - ExternalURL: buildinfo.ExternalURL(), - Version: buildinfo.Version(), - }) - }) - }) - r.Route("/updatecheck", func(r chi.Router) { - r.Get("/", api.updateCheck) - }) + r.Get("/buildinfo", buildInfo) + r.Get("/updatecheck", api.updateCheck) r.Route("/config", func(r chi.Router) { r.Use(apiKeyMiddleware) r.Get("/deployment", api.deploymentConfig) diff --git a/coderd/csp.go b/coderd/csp.go index 39719463800fb..45cc65b450b64 100644 --- a/coderd/csp.go +++ b/coderd/csp.go @@ -14,6 +14,16 @@ type cspViolation struct { Report map[string]interface{} `json:"csp-report"` } +// @Summary Report CSP violations +// @ID report-csp-violations +// @Security CoderSessionToken +// @Accept json +// @Produce text/plain +// @Tags General +// @Param request body cspViolation true "Violation report" +// @Success 200 +// @Router /csp/reports [post] +// // logReportCSPViolations will log all reported csp violations. func (api *API) logReportCSPViolations(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() diff --git a/docs/api/general.md b/docs/api/general.md new file mode 100644 index 0000000000000..ef83c65bb517e --- /dev/null +++ b/docs/api/general.md @@ -0,0 +1,111 @@ +# General + +> This page is incomplete, stay tuned. + +## API root handler + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/ \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`GET /` + +### Example responses + +> 200 Response + +```json +{ + "detail": "string", + "message": "string", + "validations": [ + { + "detail": "string", + "field": "string" + } + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. + +## Build info + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/buildinfo \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`POST /buildinfo` + +### Example responses + +> 200 Response + +```json +{ + "external_url": "string", + "version": "string" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.BuildInfoResponse](schemas.md#codersdkbuildinforesponse) | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. + +## Report CSP violations + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/csp/reports \ + -H 'Content-Type: application/json' \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`POST /csp/reports` + +> Body parameter + +```json +{ + "csp-report": {} +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ---- | ---- | ---------------------------------------------------- | -------- | ---------------- | +| body | body | [coderd.cspViolation](schemas.md#coderdcspviolation) | true | Violation report | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | --------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | no schema | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 2e9a9c0f57998..824a9961b1b26 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -2,6 +2,20 @@ > This page is incomplete, stay tuned. +## coderd.cspViolation + +```json +{ + "csp-report": {} +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------ | ------ | -------- | ------------ | ----------- | +| `csp-report` | object | false | none | none | + ## codersdk.AuthorizationCheck ```json @@ -105,6 +119,22 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | ---------------- | ------- | -------- | ------------ | ----------- | | `[any property]` | boolean | false | none | none | +## codersdk.BuildInfoResponse + +```json +{ + "external_url": "string", + "version": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `external_url` | string | false | none | External url is a URL referencing the current Coder version. For production
builds, this will link directly to a release. For development builds, this
will link to a commit. | +| `version` | string | false | none | Version returns the semantic version of the build. | + ## codersdk.CreateParameterRequest ```json diff --git a/docs/manifest.json b/docs/manifest.json index b635e8a1f8688..5e3e78386ea03 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -329,6 +329,10 @@ "title": "Authentication", "path": "./api/authentication.md" }, + { + "title": "General", + "path": "./api/general.md" + }, { "title": "Applications", "path": "./api/applications.md" From 52f0234af10c77c5e73efee6647c5326542b6f9a Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 10:06:31 +0100 Subject: [PATCH 09/28] Fix: buildinfo --- coderd/apidoc/docs.go | 2 +- coderd/apidoc/swagger.json | 2 +- coderd/buildinfo.go | 2 +- docs/api/general.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 0f1464ad5d0d2..e12e15e903ede 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -142,7 +142,7 @@ const docTemplate = `{ } }, "/buildinfo": { - "post": { + "get": { "security": [ { "CoderSessionToken": [] diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 2d925361e2f80..dcdb61832712f 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -118,7 +118,7 @@ } }, "/buildinfo": { - "post": { + "get": { "security": [ { "CoderSessionToken": [] diff --git a/coderd/buildinfo.go b/coderd/buildinfo.go index 4c592abedcac8..b913495d0f7d4 100644 --- a/coderd/buildinfo.go +++ b/coderd/buildinfo.go @@ -14,7 +14,7 @@ import ( // @Produce json // @Tags General // @Success 200 {object} codersdk.BuildInfoResponse -// @Router /buildinfo [post] +// @Router /buildinfo [get] func buildInfo(rw http.ResponseWriter, r *http.Request) { httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.BuildInfoResponse{ ExternalURL: buildinfo.ExternalURL(), diff --git a/docs/api/general.md b/docs/api/general.md index ef83c65bb517e..cefe59132bf0d 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -47,13 +47,13 @@ To perform this operation, you must be authenticated by means of one of the foll ```shell # Example request using curl -curl -X POST http://coder-server:8080/api/v2/buildinfo \ +curl -X GET http://coder-server:8080/api/v2/buildinfo \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` -`POST /buildinfo` +`GET /buildinfo` ### Example responses From 489718fe7d27f8630c1339cabc715d09695eab73 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 10:24:01 +0100 Subject: [PATCH 10/28] docs: updatecheck --- coderd/apidoc/docs.go | 47 ++++++++++++++++++++++++++++++++++---- coderd/apidoc/swagger.json | 43 ++++++++++++++++++++++++++++++---- coderd/buildinfo.go | 1 - coderd/updatecheck.go | 7 ++++++ docs/api/general.md | 39 ++++++++++++++++++++++++++++--- docs/api/schemas.md | 18 +++++++++++++++ 6 files changed, 141 insertions(+), 14 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index e12e15e903ede..a254f7fefe4f6 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -143,11 +143,6 @@ const docTemplate = `{ }, "/buildinfo": { "get": { - "security": [ - { - "CoderSessionToken": [] - } - ], "produces": [ "application/json" ], @@ -438,6 +433,31 @@ const docTemplate = `{ } } }, + "/updatecheck": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "General" + ], + "summary": "Update check", + "operationId": "update-check", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.UpdateCheckResponse" + } + } + } + } + }, "/users/{user}/workspace/{workspacename}": { "get": { "security": [ @@ -1174,6 +1194,23 @@ const docTemplate = `{ } } }, + "codersdk.UpdateCheckResponse": { + "type": "object", + "properties": { + "current": { + "description": "Current is a boolean indicating whether the\nserver version is the same as the latest.", + "type": "boolean" + }, + "url": { + "description": "URL to download the latest release of Coder.", + "type": "string" + }, + "version": { + "description": "Version is the semantic version for the latest\nrelease of Coder.", + "type": "string" + } + } + }, "codersdk.UpdateWorkspaceAutostartRequest": { "type": "object", "properties": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index dcdb61832712f..510911ed4a7a7 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -119,11 +119,6 @@ }, "/buildinfo": { "get": { - "security": [ - { - "CoderSessionToken": [] - } - ], "produces": ["application/json"], "tags": ["General"], "summary": "Build info", @@ -378,6 +373,27 @@ } } }, + "/updatecheck": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["General"], + "summary": "Update check", + "operationId": "update-check", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.UpdateCheckResponse" + } + } + } + } + }, "/users/{user}/workspace/{workspacename}": { "get": { "security": [ @@ -1054,6 +1070,23 @@ } } }, + "codersdk.UpdateCheckResponse": { + "type": "object", + "properties": { + "current": { + "description": "Current is a boolean indicating whether the\nserver version is the same as the latest.", + "type": "boolean" + }, + "url": { + "description": "URL to download the latest release of Coder.", + "type": "string" + }, + "version": { + "description": "Version is the semantic version for the latest\nrelease of Coder.", + "type": "string" + } + } + }, "codersdk.UpdateWorkspaceAutostartRequest": { "type": "object", "properties": { diff --git a/coderd/buildinfo.go b/coderd/buildinfo.go index b913495d0f7d4..76497f8990e8a 100644 --- a/coderd/buildinfo.go +++ b/coderd/buildinfo.go @@ -10,7 +10,6 @@ import ( // @Summary Build info // @ID build-info -// @Security CoderSessionToken // @Produce json // @Tags General // @Success 200 {object} codersdk.BuildInfoResponse diff --git a/coderd/updatecheck.go b/coderd/updatecheck.go index a2c08ad879157..2aa796fcd047e 100644 --- a/coderd/updatecheck.go +++ b/coderd/updatecheck.go @@ -13,6 +13,13 @@ import ( "github.com/coder/coder/codersdk" ) +// @Summary Update check +// @ID update-check +// @Security CoderSessionToken +// @Produce json +// @Tags General +// @Success 200 {object} codersdk.UpdateCheckResponse +// @Router /updatecheck [get] func (api *API) updateCheck(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() diff --git a/docs/api/general.md b/docs/api/general.md index cefe59132bf0d..99d8f160d7339 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -48,8 +48,7 @@ To perform this operation, you must be authenticated by means of one of the foll ```shell # Example request using curl curl -X GET http://coder-server:8080/api/v2/buildinfo \ - -H 'Accept: application/json' \ - -H 'Coder-Session-Token: API_KEY' + -H 'Accept: application/json' ``` @@ -72,7 +71,7 @@ curl -X GET http://coder-server:8080/api/v2/buildinfo \ | ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------ | | 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.BuildInfoResponse](schemas.md#codersdkbuildinforesponse) | -To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. +undefined ## Report CSP violations @@ -109,3 +108,37 @@ curl -X POST http://coder-server:8080/api/v2/csp/reports \ | 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | no schema | To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. + +## Update check + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/updatecheck \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' + +``` + +`GET /updatecheck` + +### Example responses + +> 200 Response + +```json +{ + "current": true, + "url": "string", + "version": "string" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.UpdateCheckResponse](schemas.md#codersdkupdatecheckresponse) | + +To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 824a9961b1b26..548d197183cc6 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -416,6 +416,24 @@ CreateParameterRequest is a structure used to create a new parameter value for a | `p50` | integer | false | none | none | | `p95` | integer | false | none | none | +## codersdk.UpdateCheckResponse + +```json +{ + "current": true, + "url": "string", + "version": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| --------- | ------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `current` | boolean | false | none | Current is a boolean indicating whether the
server version is the same as the latest. | +| `url` | string | false | none | Url to download the latest release of Coder. | +| `version` | string | false | none | Version is the semantic version for the latest
release of Coder. | + ## codersdk.UpdateWorkspaceAutostartRequest ```json From 40291615d946cadb0cf422bfebbff9603dcd9d95 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 10:26:55 +0100 Subject: [PATCH 11/28] docs: apiroot --- coderd/apidoc/docs.go | 5 ----- coderd/apidoc/swagger.json | 5 ----- coderd/apiroot.go | 1 - docs/api/general.md | 5 ++--- 4 files changed, 2 insertions(+), 14 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index a254f7fefe4f6..bfe1fa87f37d4 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -27,11 +27,6 @@ const docTemplate = `{ "paths": { "/": { "get": { - "security": [ - { - "CoderSessionToken": [] - } - ], "produces": [ "application/json" ], diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 510911ed4a7a7..db0908f3f6112 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -19,11 +19,6 @@ "paths": { "/": { "get": { - "security": [ - { - "CoderSessionToken": [] - } - ], "produces": ["application/json"], "tags": ["General"], "summary": "API root handler", diff --git a/coderd/apiroot.go b/coderd/apiroot.go index 29c43a4eba544..6974ca5133e24 100644 --- a/coderd/apiroot.go +++ b/coderd/apiroot.go @@ -9,7 +9,6 @@ import ( // @Summary API root handler // @ID api-root-handler -// @Security CoderSessionToken // @Produce json // @Tags General // @Success 200 {object} codersdk.Response diff --git a/docs/api/general.md b/docs/api/general.md index 99d8f160d7339..a17febec62cd6 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -9,8 +9,7 @@ ```shell # Example request using curl curl -X GET http://coder-server:8080/api/v2/ \ - -H 'Accept: application/json' \ - -H 'Coder-Session-Token: API_KEY' + -H 'Accept: application/json' ``` @@ -39,7 +38,7 @@ curl -X GET http://coder-server:8080/api/v2/ \ | ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ | | 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) | -To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. +undefined ## Build info From e8286f6be67473506e1e040e44d410f90513038a Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 13:53:50 +0100 Subject: [PATCH 12/28] Fix: s/none//g --- docs/api/schemas.md | 304 +++++++++--------- docs/api/templates.md | 42 +-- scripts/apidocgen/markdown-template/main.dot | 6 +- .../apidocgen/markdown-template/responses.def | 6 +- 4 files changed, 179 insertions(+), 179 deletions(-) diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 2e9a9c0f57998..7e40696ae883f 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -22,8 +22,8 @@ AuthorizationCheck is used to check if the currently authenticated user (or the | Name | Type | Required | Restrictions | Description | | -------- | ------------------------------------------------------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `action` | string | false | none | none | -| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | none | Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. | +| `action` | string | false | | | +| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | | Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. | #### Enumerated Values @@ -51,10 +51,10 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | Name | Type | Required | Restrictions | Description | | ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organization_id` | string | false | none | Organization id (optional) adds the set constraint to all resources owned by a given organization. | -| `owner_id` | string | false | none | Owner id (optional) adds the set constraint to all resources owned by a given user. | -| `resource_id` | string | false | none | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the `OwnerID` and `OrganizationID`
if possible. Be as specific as possible using all the fields relevant. | -| `resource_type` | string | false | none | Resource type is the name of the resource.
`./coderd/rbac/object.go` has the list of valid resource types. | +| `organization_id` | string | false | | Organization id (optional) adds the set constraint to all resources owned by a given organization. | +| `owner_id` | string | false | | Owner id (optional) adds the set constraint to all resources owned by a given user. | +| `resource_id` | string | false | | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the `OwnerID` and `OrganizationID`
if possible. Be as specific as possible using all the fields relevant. | +| `resource_type` | string | false | | Resource type is the name of the resource.
`./coderd/rbac/object.go` has the list of valid resource types. | ## codersdk.AuthorizationRequest @@ -87,8 +87,8 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | Name | Type | Required | Restrictions | Description | | ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `checks` | object | false | none | Checks is a map keyed with an arbitrary string to a permission check.
The key can be any string that is helpful to the caller, and allows
multiple permission checks to be run in a single request.
The key ensures that each permission check has the same key in the
response. | -| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | none | » **additionalproperties** is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | +| `checks` | object | false | | Checks is a map keyed with an arbitrary string to a permission check.
The key can be any string that is helpful to the caller, and allows
multiple permission checks to be run in a single request.
The key ensures that each permission check has the same key in the
response. | +| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | | » **additionalproperties** is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | ## codersdk.AuthorizationResponse @@ -103,7 +103,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | Name | Type | Required | Restrictions | Description | | ---------------- | ------- | -------- | ------------ | ----------- | -| `[any property]` | boolean | false | none | none | +| `[any property]` | boolean | false | | | ## codersdk.CreateParameterRequest @@ -123,11 +123,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | --------------------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `copy_from_parameter` | string | false | none | Copy from parameter allows copying the value of another parameter.
The other param must be related to the same template_id for this to
succeed.
No other fields are required if using this, as all fields will be copied
from the other parameter. | -| `destination_scheme` | string | true | none | none | -| `name` | string | true | none | none | -| `source_scheme` | string | true | none | none | -| `source_value` | string | true | none | none | +| `copy_from_parameter` | string | false | | Copy from parameter allows copying the value of another parameter.
The other param must be related to the same template_id for this to
succeed.
No other fields are required if using this, as all fields will be copied
from the other parameter. | +| `destination_scheme` | string | true | | | +| `name` | string | true | | | +| `source_scheme` | string | true | | | +| `source_value` | string | true | | | #### Enumerated Values @@ -164,14 +164,14 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------------------------------- | --------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `allow_user_cancel_workspace_jobs` | boolean | false | none | Allow users to cancel in-progress workspace jobs.
\*bool as the default value is "true". | -| `default_ttl_ms` | integer | false | none | Default ttl ms allows optionally specifying the default TTL
for all workspaces created from this template. | -| `description` | string | false | none | Description is a description of what the template contains. It must be
less than 128 bytes. | -| `display_name` | string | false | none | Display name is the displayed name of the template. | -| `icon` | string | false | none | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `name` | string | true | none | Name is the name of the template. | -| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | none | Parameter values is a structure used to create a new parameter value for a scope.] | -| `template_version_id` | string | true | none | Template version id is an in-progress or completed job to use as an initial version
of the template.

This is required on creation to enable a user-flow of validating a
template works. There is no reason the data-model cannot support empty
templates, but it doesn't make sense for users. | +| `allow_user_cancel_workspace_jobs` | boolean | false | | Allow users to cancel in-progress workspace jobs.
\*bool as the default value is "true". | +| `default_ttl_ms` | integer | false | | Default ttl ms allows optionally specifying the default TTL
for all workspaces created from this template. | +| `description` | string | false | | Description is a description of what the template contains. It must be
less than 128 bytes. | +| `display_name` | string | false | | Display name is the displayed name of the template. | +| `icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | +| `name` | string | true | | Name is the name of the template. | +| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | | Parameter values is a structure used to create a new parameter value for a scope.] | +| `template_version_id` | string | true | | Template version id is an in-progress or completed job to use as an initial version
of the template.

This is required on creation to enable a user-flow of validating a
template works. There is no reason the data-model cannot support empty
templates, but it doesn't make sense for users. | ## codersdk.DERPRegion @@ -186,8 +186,8 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------------ | ------- | -------- | ------------ | ----------- | -| `latency_ms` | number | false | none | none | -| `preferred` | boolean | false | none | none | +| `latency_ms` | number | false | | | +| `preferred` | boolean | false | | | ## codersdk.GetAppHostResponse @@ -201,7 +201,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------ | ------ | -------- | ------------ | ------------------------------------------------------------- | -| `host` | string | false | none | Host is the externally accessible URL for the Coder instance. | +| `host` | string | false | | Host is the externally accessible URL for the Coder instance. | ## codersdk.Healthcheck @@ -217,9 +217,9 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ----------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------ | -| `interval` | integer | false | none | Interval specifies the seconds between each health check. | -| `threshold` | integer | false | none | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | -| `url` | string | false | none | Url specifies the url to check for the app health. | +| `interval` | integer | false | | Interval specifies the seconds between each health check. | +| `threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | +| `url` | string | false | | Url specifies the url to check for the app health. | ## codersdk.ProvisionerJob @@ -245,17 +245,17 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------------------ | ------ | -------- | ------------ | ----------- | -| `canceled_at` | string | false | none | none | -| `completed_at` | string | false | none | none | -| `created_at` | string | false | none | none | -| `error` | string | false | none | none | -| `file_id` | string | false | none | none | -| `id` | string | false | none | none | -| `started_at` | string | false | none | none | -| `status` | string | false | none | none | -| `tags` | object | false | none | none | -| » `[any property]` | string | false | none | none | -| `worker_id` | string | false | none | none | +| `canceled_at` | string | false | | | +| `completed_at` | string | false | | | +| `created_at` | string | false | | | +| `error` | string | false | | | +| `file_id` | string | false | | | +| `id` | string | false | | | +| `started_at` | string | false | | | +| `status` | string | false | | | +| `tags` | object | false | | | +| » `[any property]` | string | false | | | +| `worker_id` | string | false | | | ## codersdk.PutExtendWorkspaceRequest @@ -269,7 +269,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------- | ------ | -------- | ------------ | ----------- | -| `deadline` | string | true | none | none | +| `deadline` | string | true | | | ## codersdk.Response @@ -290,9 +290,9 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------------- | ------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `detail` | string | false | none | Detail is a debug message that provides further insight into why the
action failed. This information can be technical and a regular golang
err.Error() text.
- "database: too many open connections"
- "stat: too many open files" | -| `message` | string | false | none | Message is an actionable message that depicts actions the request took.
These messages should be fully formed sentences with proper punctuation.
Examples:
- "A user has been created."
- "Failed to create a user." | -| `validations` | array of [codersdk.ValidationError](#codersdkvalidationerror) | false | none | Validations are form field-specific friendly error messages. They will be
shown on a form field in the UI. These can also be used to add additional
context if there is a set of errors in the primary 'Message'. | +| `detail` | string | false | | Detail is a debug message that provides further insight into why the
action failed. This information can be technical and a regular golang
err.Error() text.
- "database: too many open connections"
- "stat: too many open files" | +| `message` | string | false | | Message is an actionable message that depicts actions the request took.
These messages should be fully formed sentences with proper punctuation.
Examples:
- "A user has been created."
- "Failed to create a user." | +| `validations` | array of [codersdk.ValidationError](#codersdkvalidationerror) | false | | Validations are form field-specific friendly error messages. They will be
shown on a form field in the UI. These can also be used to add additional
context if there is a set of errors in the primary 'Message'. | ## codersdk.Template @@ -331,23 +331,23 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------------------------------- | ------------------------------------------------------------------ | -------- | ------------ | -------------------------------------------- | -| `active_user_count` | integer | false | none | Active user count is set to -1 when loading. | -| `active_version_id` | string | false | none | none | -| `allow_user_cancel_workspace_jobs` | boolean | false | none | none | -| `build_time_stats` | [codersdk.TemplateBuildTimeStats](#codersdktemplatebuildtimestats) | false | none | none | -| `created_at` | string | false | none | none | -| `created_by_id` | string | false | none | none | -| `created_by_name` | string | false | none | none | -| `default_ttl_ms` | integer | false | none | none | -| `description` | string | false | none | none | -| `display_name` | string | false | none | none | -| `icon` | string | false | none | none | -| `id` | string | false | none | none | -| `name` | string | false | none | none | -| `organization_id` | string | false | none | none | -| `provisioner` | string | false | none | none | -| `updated_at` | string | false | none | none | -| `workspace_owner_count` | integer | false | none | none | +| `active_user_count` | integer | false | | Active user count is set to -1 when loading. | +| `active_version_id` | string | false | | | +| `allow_user_cancel_workspace_jobs` | boolean | false | | | +| `build_time_stats` | [codersdk.TemplateBuildTimeStats](#codersdktemplatebuildtimestats) | false | | | +| `created_at` | string | false | | | +| `created_by_id` | string | false | | | +| `created_by_name` | string | false | | | +| `default_ttl_ms` | integer | false | | | +| `description` | string | false | | | +| `display_name` | string | false | | | +| `icon` | string | false | | | +| `id` | string | false | | | +| `name` | string | false | | | +| `organization_id` | string | false | | | +| `provisioner` | string | false | | | +| `updated_at` | string | false | | | +| `workspace_owner_count` | integer | false | | | ## codersdk.TemplateBuildTimeStats @@ -368,7 +368,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------------- | ---------------------------------------------------- | -------- | ------------ | ----------- | -| `[any property]` | [codersdk.TransitionStats](#codersdktransitionstats) | false | none | none | +| `[any property]` | [codersdk.TransitionStats](#codersdktransitionstats) | false | | | ## codersdk.TransitionStats @@ -383,8 +383,8 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ----- | ------- | -------- | ------------ | ----------- | -| `p50` | integer | false | none | none | -| `p95` | integer | false | none | none | +| `p50` | integer | false | | | +| `p95` | integer | false | | | ## codersdk.UpdateWorkspaceAutostartRequest @@ -398,7 +398,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------- | ------ | -------- | ------------ | ----------- | -| `schedule` | string | false | none | none | +| `schedule` | string | false | | | ## codersdk.UpdateWorkspaceRequest @@ -412,7 +412,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------ | ------ | -------- | ------------ | ----------- | -| `name` | string | false | none | none | +| `name` | string | false | | | ## codersdk.UpdateWorkspaceTTLRequest @@ -426,7 +426,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | -------- | ------- | -------- | ------------ | ----------- | -| `ttl_ms` | integer | false | none | none | +| `ttl_ms` | integer | false | | | ## codersdk.ValidationError @@ -441,8 +441,8 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | -------- | ------ | -------- | ------------ | ----------- | -| `detail` | string | true | none | none | -| `field` | string | true | none | none | +| `detail` | string | true | | | +| `field` | string | true | | | ## codersdk.Workspace @@ -581,22 +581,22 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------------------------------------------- | -------------------------------------------------- | -------- | ------------ | ----------- | -| `autostart_schedule` | string | false | none | none | -| `created_at` | string | false | none | none | -| `id` | string | false | none | none | -| `last_used_at` | string | false | none | none | -| `latest_build` | [codersdk.WorkspaceBuild](#codersdkworkspacebuild) | false | none | none | -| `name` | string | false | none | none | -| `outdated` | boolean | false | none | none | -| `owner_id` | string | false | none | none | -| `owner_name` | string | false | none | none | -| `template_allow_user_cancel_workspace_jobs` | boolean | false | none | none | -| `template_display_name` | string | false | none | none | -| `template_icon` | string | false | none | none | -| `template_id` | string | false | none | none | -| `template_name` | string | false | none | none | -| `ttl_ms` | integer | false | none | none | -| `updated_at` | string | false | none | none | +| `autostart_schedule` | string | false | | | +| `created_at` | string | false | | | +| `id` | string | false | | | +| `last_used_at` | string | false | | | +| `latest_build` | [codersdk.WorkspaceBuild](#codersdkworkspacebuild) | false | | | +| `name` | string | false | | | +| `outdated` | boolean | false | | | +| `owner_id` | string | false | | | +| `owner_name` | string | false | | | +| `template_allow_user_cancel_workspace_jobs` | boolean | false | | | +| `template_display_name` | string | false | | | +| `template_icon` | string | false | | | +| `template_id` | string | false | | | +| `template_name` | string | false | | | +| `ttl_ms` | integer | false | | | +| `updated_at` | string | false | | | ## codersdk.WorkspaceAgent @@ -659,28 +659,28 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------------------------- | ------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------- | -| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | none | none | -| `architecture` | string | false | none | none | -| `connection_timeout_seconds` | integer | false | none | none | -| `created_at` | string | false | none | none | -| `directory` | string | false | none | none | -| `disconnected_at` | string | false | none | none | -| `environment_variables` | object | false | none | none | -| » `[any property]` | string | false | none | none | -| `first_connected_at` | string | false | none | none | -| `id` | string | false | none | none | -| `instance_id` | string | false | none | none | -| `last_connected_at` | string | false | none | none | -| `latency` | object | false | none | Latency is mapped by region name (e.g. "New York City", "Seattle"). | -| » `[any property]` | [codersdk.DERPRegion](#codersdkderpregion) | false | none | none | -| `name` | string | false | none | none | -| `operating_system` | string | false | none | none | -| `resource_id` | string | false | none | none | -| `startup_script` | string | false | none | none | -| `status` | string | false | none | none | -| `troubleshooting_url` | string | false | none | none | -| `updated_at` | string | false | none | none | -| `version` | string | false | none | none | +| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | | | +| `architecture` | string | false | | | +| `connection_timeout_seconds` | integer | false | | | +| `created_at` | string | false | | | +| `directory` | string | false | | | +| `disconnected_at` | string | false | | | +| `environment_variables` | object | false | | | +| » `[any property]` | string | false | | | +| `first_connected_at` | string | false | | | +| `id` | string | false | | | +| `instance_id` | string | false | | | +| `last_connected_at` | string | false | | | +| `latency` | object | false | | Latency is mapped by region name (e.g. "New York City", "Seattle"). | +| » `[any property]` | [codersdk.DERPRegion](#codersdkderpregion) | false | | | +| `name` | string | false | | | +| `operating_system` | string | false | | | +| `resource_id` | string | false | | | +| `startup_script` | string | false | | | +| `status` | string | false | | | +| `troubleshooting_url` | string | false | | | +| `updated_at` | string | false | | | +| `version` | string | false | | | ## codersdk.WorkspaceApp @@ -708,17 +708,17 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | --------------- | -------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `command` | string | false | none | none | -| `display_name` | string | false | none | Display name is a friendly name for the app. | -| `external` | boolean | false | none | External specifies whether the URL should be opened externally on
the client or not. | -| `health` | string | false | none | none | -| `healthcheck` | [codersdk.Healthcheck](#codersdkhealthcheck) | false | none | none | -| `icon` | string | false | none | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `id` | string | false | none | none | -| `sharing_level` | string | false | none | none | -| `slug` | string | false | none | Slug is a unique identifier within the agent. | -| `subdomain` | boolean | false | none | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | -| `url` | string | false | none | Url is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | +| `command` | string | false | | | +| `display_name` | string | false | | Display name is a friendly name for the app. | +| `external` | boolean | false | | External specifies whether the URL should be opened externally on
the client or not. | +| `health` | string | false | | | +| `healthcheck` | [codersdk.Healthcheck](#codersdkhealthcheck) | false | | | +| `icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | +| `id` | string | false | | | +| `sharing_level` | string | false | | | +| `slug` | string | false | | Slug is a unique identifier within the agent. | +| `subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | +| `url` | string | false | | Url is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | ## codersdk.WorkspaceBuild @@ -840,25 +840,25 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ----------------------- | ----------------------------------------------------------------- | -------- | ------------ | ----------- | -| `build_number` | integer | false | none | none | -| `created_at` | string | false | none | none | -| `daily_cost` | integer | false | none | none | -| `deadline` | string(time) or `null` | false | none | none | -| `id` | string | false | none | none | -| `initiator_id` | string | false | none | none | -| `initiator_name` | string | false | none | none | -| `job` | [codersdk.ProvisionerJob](#codersdkprovisionerjob) | false | none | none | -| `reason` | string | false | none | none | -| `resources` | array of [codersdk.WorkspaceResource](#codersdkworkspaceresource) | false | none | none | -| `status` | string | false | none | none | -| `template_version_id` | string | false | none | none | -| `template_version_name` | string | false | none | none | -| `transition` | string | false | none | none | -| `updated_at` | string | false | none | none | -| `workspace_id` | string | false | none | none | -| `workspace_name` | string | false | none | none | -| `workspace_owner_id` | string | false | none | none | -| `workspace_owner_name` | string | false | none | none | +| `build_number` | integer | false | | | +| `created_at` | string | false | | | +| `daily_cost` | integer | false | | | +| `deadline` | string(time) or `null` | false | | | +| `id` | string | false | | | +| `initiator_id` | string | false | | | +| `initiator_name` | string | false | | | +| `job` | [codersdk.ProvisionerJob](#codersdkprovisionerjob) | false | | | +| `reason` | string | false | | | +| `resources` | array of [codersdk.WorkspaceResource](#codersdkworkspaceresource) | false | | | +| `status` | string | false | | | +| `template_version_id` | string | false | | | +| `template_version_name` | string | false | | | +| `transition` | string | false | | | +| `updated_at` | string | false | | | +| `workspace_id` | string | false | | | +| `workspace_name` | string | false | | | +| `workspace_owner_id` | string | false | | | +| `workspace_owner_name` | string | false | | | #### Enumerated Values @@ -959,17 +959,17 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ---------------------- | --------------------------------------------------------------------------------- | -------- | ------------ | ----------- | -| `agents` | array of [codersdk.WorkspaceAgent](#codersdkworkspaceagent) | false | none | none | -| `created_at` | string | false | none | none | -| `daily_cost` | integer | false | none | none | -| `hide` | boolean | false | none | none | -| `icon` | string | false | none | none | -| `id` | string | false | none | none | -| `job_id` | string | false | none | none | -| `metadata` | array of [codersdk.WorkspaceResourceMetadata](#codersdkworkspaceresourcemetadata) | false | none | none | -| `name` | string | false | none | none | -| `type` | string | false | none | none | -| `workspace_transition` | string | false | none | none | +| `agents` | array of [codersdk.WorkspaceAgent](#codersdkworkspaceagent) | false | | | +| `created_at` | string | false | | | +| `daily_cost` | integer | false | | | +| `hide` | boolean | false | | | +| `icon` | string | false | | | +| `id` | string | false | | | +| `job_id` | string | false | | | +| `metadata` | array of [codersdk.WorkspaceResourceMetadata](#codersdkworkspaceresourcemetadata) | false | | | +| `name` | string | false | | | +| `type` | string | false | | | +| `workspace_transition` | string | false | | | #### Enumerated Values @@ -993,9 +993,9 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ----------- | ------- | -------- | ------------ | ----------- | -| `key` | string | false | none | none | -| `sensitive` | boolean | false | none | none | -| `value` | string | false | none | none | +| `key` | string | false | | | +| `sensitive` | boolean | false | | | +| `value` | string | false | | | ## codersdk.WorkspacesResponse @@ -1135,5 +1135,5 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | ------------ | ------------------------------------------------- | -------- | ------------ | ----------- | -| `count` | integer | false | none | none | -| `workspaces` | array of [codersdk.Workspace](#codersdkworkspace) | false | none | none | +| `count` | integer | false | | | +| `workspaces` | array of [codersdk.Workspace](#codersdkworkspace) | false | | | diff --git a/docs/api/templates.md b/docs/api/templates.md index cd912e200270a..dde8696c94072 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -159,27 +159,27 @@ Status Code **200** | Name | Type | Required | Restrictions | Description | | ---------------------------------- | --------------------------------- | -------- | ------------ | ------------------------------------------ | -| _anonymous_ | array | false | none | none | -| » active_user_count | integer | false | none | ActiveUserCount is set to -1 when loading. | -| » active_version_id | string | false | none | none | -| » allow_user_cancel_workspace_jobs | boolean | false | none | none | -| » build_time_stats | `codersdk.TemplateBuildTimeStats` | false | none | none | -| »» **additionalProperties** | `codersdk.TransitionStats` | false | none | none | -| »»» p50 | integer | false | none | none | -| »»» p95 | integer | false | none | none | -| » created_at | string | false | none | none | -| » created_by_id | string | false | none | none | -| » created_by_name | string | false | none | none | -| » default_ttl_ms | integer | false | none | none | -| » description | string | false | none | none | -| » display_name | string | false | none | none | -| » icon | string | false | none | none | -| » id | string | false | none | none | -| » name | string | false | none | none | -| » organization_id | string | false | none | none | -| » provisioner | string | false | none | none | -| » updated_at | string | false | none | none | -| » workspace_owner_count | integer | false | none | none | +| _anonymous_ | array | false | | | +| » active_user_count | integer | false | | ActiveUserCount is set to -1 when loading. | +| » active_version_id | string | false | | | +| » allow_user_cancel_workspace_jobs | boolean | false | | | +| » build_time_stats | `codersdk.TemplateBuildTimeStats` | false | | | +| »» **additionalProperties** | `codersdk.TransitionStats` | false | | | +| »»» p50 | integer | false | | | +| »»» p95 | integer | false | | | +| » created_at | string | false | | | +| » created_by_id | string | false | | | +| » created_by_name | string | false | | | +| » default_ttl_ms | integer | false | | | +| » description | string | false | | | +| » display_name | string | false | | | +| » icon | string | false | | | +| » id | string | false | | | +| » name | string | false | | | +| » organization_id | string | false | | | +| » provisioner | string | false | | | +| » updated_at | string | false | | | +| » workspace_owner_count | integer | false | | | To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index e325a61d37349..989608cc1c157 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -30,7 +30,7 @@ function renderDescription(p) { if (!p.description) { - return "none"; + return ""; } const toSnakeCase = str => @@ -41,7 +41,7 @@ const words = p.description.split(' '); if (words.length == 0) { - return "none"; + return ""; } const countUppercase = words[0].length - words[0].replace(/[A-Z]/g, '').length; @@ -130,7 +130,7 @@ {{? block.rows.length}}|Name|Type|Required|Restrictions|Description| |---|---|---|---|---|{{?}} -{{~ block.rows :p}}|{{= renderDisplayName(p)}}|{{= renderPropertyType(p)}}|{{=p.required}}|{{=p.restrictions||'none'}}|{{= renderDescription(p)}}| +{{~ block.rows :p}}|{{= renderDisplayName(p)}}|{{= renderPropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{= renderDescription(p)}}| {{~}} {{~}} {{? (blocks[0].rows.length === 0) && (blocks.length === 1) }} diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index d454f6ce9ad43..b9d3c7c3b50be 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -42,7 +42,7 @@ |Status|Meaning|Description|Schema| |---|---|---|---| -{{~ data.responses :r}}|{{=r.status}}|{{=r.meaning}}|{{=r.description || 'none'}}|{{= renderResponseType(r)}}| +{{~ data.responses :r}}|{{=r.status}}|{{=r.meaning}}|{{=r.description||''}}|{{= renderResponseType(r)}}| {{~}} {{ data.responseSchemas = false; }} @@ -77,7 +77,7 @@ Status Code **{{=response.status}}** {{?}} |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| -{{~block.rows :p}}|{{=p.displayName}}|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||'none'}}|{{=p.description||'none'}}| +{{~block.rows :p}}|{{=p.displayName}}|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}| {{~}} {{~}} {{?}} @@ -106,7 +106,7 @@ Status Code **{{=response.status}}** |Status|Header|Type|Format|Description| |---|---|---|---|---| -{{~ data.responseHeaders :h}}|{{=h.status}}|{{=h.header}}|{{=h.type}}|{{=h.format||''}}|{{=h.description||'none'}}| +{{~ data.responseHeaders :h}}|{{=h.status}}|{{=h.header}}|{{=h.type}}|{{=h.format||''}}|{{=h.description||''}}| {{~}} {{?}} From 60e0f279e8f06e7d2b7742a583304f296f4a6116 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 14:07:25 +0100 Subject: [PATCH 13/28] Fix: godoc nice --- coderd/authorize.go | 6 +++--- codersdk/parameters.go | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/coderd/authorize.go b/coderd/authorize.go index 6f5a5f63e1a9e..3acdd3d1d9647 100644 --- a/coderd/authorize.go +++ b/coderd/authorize.go @@ -104,6 +104,9 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action, return prepared, nil } +// checkAuthorization returns if the current API key can use the given +// permissions, factoring in the current user's roles and the API key scopes. +// // @Summary Check authorization // @ID check-authorization // @Security CoderSessionToken @@ -113,9 +116,6 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action, // @Param request body codersdk.AuthorizationRequest true "Authorization request" // @Success 200 {object} codersdk.AuthorizationResponse // @Router /authcheck [post] -// -// checkAuthorization returns if the current API key can use the given -// permissions, factoring in the current user's roles and the API key scopes. func (api *API) checkAuthorization(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() auth := httpmw.UserAuthorization(r) diff --git a/codersdk/parameters.go b/codersdk/parameters.go index de8f86d4b1bc0..c813096412a11 100644 --- a/codersdk/parameters.go +++ b/codersdk/parameters.go @@ -83,6 +83,8 @@ type ParameterSchema struct { ValidationContains []string `json:"validation_contains,omitempty"` } +// CreateParameterRequest is a structure used to create a new parameter value for a scope. +// // @Description CreateParameterRequest is a structure used to create a new parameter value for a scope. type CreateParameterRequest struct { // CloneID allows copying the value of another parameter. From 74de5d459f8bb14622865a9897766fd2959e19c9 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 14:11:33 +0100 Subject: [PATCH 14/28] Fix: description --- codersdk/authorization.go | 8 ++++++-- scripts/apidocgen/markdown-template/parameters.def | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/codersdk/authorization.go b/codersdk/authorization.go index 4d4f1f13924bf..64e9eeec3ff77 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -20,8 +20,9 @@ type AuthorizationRequest struct { Checks map[string]AuthorizationCheck `json:"checks"` } -// @Description AuthorizationCheck is used to check if the currently authenticated user (or -// @Description the specified user) can do a given action to a given set of objects. +// AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. +// +// @Description AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. type AuthorizationCheck struct { // Object can represent a "set" of objects, such as: // - All workspaces in an organization @@ -37,6 +38,9 @@ type AuthorizationCheck struct { Action string `json:"action" enums:"create,read,update,delete"` } +// AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, +// all workspaces across the entire product. +// // @Description AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, // @Description all workspaces across the entire product. type AuthorizationObject struct { diff --git a/scripts/apidocgen/markdown-template/parameters.def b/scripts/apidocgen/markdown-template/parameters.def index e44ab119b1a09..1b00563cb37f4 100644 --- a/scripts/apidocgen/markdown-template/parameters.def +++ b/scripts/apidocgen/markdown-template/parameters.def @@ -13,7 +13,7 @@ |Name|In|Type|Required|Description| |---|---|---|---|---| -{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{= renderParameterType(p)}}|{{=p.required}}|{{=p.shortDesc || 'none'}}| +{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{= renderParameterType(p)}}|{{=p.required}}|{{=p.shortDesc||''}}| {{~}} {{? data.longDescs }} From 095a46308e874324aa55acff5b2e6e0ddacba645 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 14:33:37 +0100 Subject: [PATCH 15/28] Fix: It --- docs/api/schemas.md | 2 +- scripts/apidocgen/markdown-template/main.dot | 9 ++------- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 7e40696ae883f..1eb92eef76651 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -88,7 +88,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | Name | Type | Required | Restrictions | Description | | ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `checks` | object | false | | Checks is a map keyed with an arbitrary string to a permission check.
The key can be any string that is helpful to the caller, and allows
multiple permission checks to be run in a single request.
The key ensures that each permission check has the same key in the
response. | -| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | | » **additionalproperties** is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | +| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | | It is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | ## codersdk.AuthorizationResponse diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index 989608cc1c157..26df1e67855e2 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -33,12 +33,6 @@ return ""; } - const toSnakeCase = str => - str - .match(/[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g) - .map(x => x.toLowerCase()) - .join('_'); - const words = p.description.split(' '); if (words.length == 0) { return ""; @@ -46,7 +40,8 @@ const countUppercase = words[0].length - words[0].replace(/[A-Z]/g, '').length; if (countUppercase > 1) { - const displayName = p.displayName.charAt(0).toUpperCase() + p.displayName.replaceAll("_", " ").toLowerCase().slice(1); + let displayName = p.displayName.replaceAll("» **additionalProperties**", "It"); + displayName = displayName.charAt(0).toUpperCase() + displayName.replaceAll("_", " ").toLowerCase().slice(1); return displayName + " " + words.slice(1).join(' '); } return p.description; From 4719a181308eb48d998c974ed97d5f40aec2d1bc Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 14:44:30 +0100 Subject: [PATCH 16/28] Fix: code sample trim empty line --- docs/api/applications.md | 2 -- docs/api/authorization.md | 1 - docs/api/templates.md | 5 ----- docs/api/workspaces.md | 9 --------- scripts/apidocgen/markdown-template/code_shell.dot | 4 ++-- scripts/apidocgen/markdown-template/operation.dot | 8 +++++++- 6 files changed, 9 insertions(+), 20 deletions(-) diff --git a/docs/api/applications.md b/docs/api/applications.md index 37e9eec8d5f4e..fa283b4d02505 100644 --- a/docs/api/applications.md +++ b/docs/api/applications.md @@ -10,7 +10,6 @@ # Example request using curl curl -X GET http://coder-server:8080/api/v2/applications/auth-redirect \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /applications/auth-redirect` @@ -38,7 +37,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/applications/host \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /applications/host` diff --git a/docs/api/authorization.md b/docs/api/authorization.md index c9cc3ee885df7..7fc0d08267399 100644 --- a/docs/api/authorization.md +++ b/docs/api/authorization.md @@ -12,7 +12,6 @@ curl -X POST http://coder-server:8080/api/v2/authcheck \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `POST /authcheck` diff --git a/docs/api/templates.md b/docs/api/templates.md index dde8696c94072..48301afd108f9 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -12,7 +12,6 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization-id}/tem -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `POST /organizations/{organization-id}/templates/` @@ -99,7 +98,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /organizations/{organization}/templates` @@ -192,7 +190,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates/{template-name} \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /organizations/{organization}/templates/{template-name}` @@ -256,7 +253,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/templates/{id} \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /templates/{id}` @@ -319,7 +315,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X DELETE http://coder-server:8080/api/v2/templates/{id} \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `DELETE /templates/{id}` diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index 0fa6684b6e0c7..f6fc0592a84be 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -11,7 +11,6 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/members/{user}/workspaces \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `POST /organizations/{organization}/members/{user}/workspaces` @@ -175,7 +174,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacename} \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /users/{user}/workspace/{workspacename}` @@ -340,7 +338,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/workspaces \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /workspaces` @@ -526,7 +523,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/workspaces/{id} \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /workspaces/{id}` @@ -690,7 +686,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X PATCH http://coder-server:8080/api/v2/workspaces/{workspace} \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `PATCH /workspaces/{workspace}` @@ -727,7 +722,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/autostart \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `PUT /workspaces/{workspace}/autostart` @@ -765,7 +759,6 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/extend \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `PUT /workspaces/{workspace}/extend` @@ -819,7 +812,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/ttl \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `PUT /workspaces/{workspace}/ttl` @@ -856,7 +848,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/workspaces/{workspace}/watch \ -H 'Accept: text/event-stream' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /workspaces/{workspace}/watch` diff --git a/scripts/apidocgen/markdown-template/code_shell.dot b/scripts/apidocgen/markdown-template/code_shell.dot index fea528a807052..041b3d92a0344 100644 --- a/scripts/apidocgen/markdown-template/code_shell.dot +++ b/scripts/apidocgen/markdown-template/code_shell.dot @@ -1,4 +1,4 @@ # Example request using curl curl -X {{=data.methodUpper}} http://coder-server:8080{{=data.url}}{{=data.requiredQueryString}}{{?data.allHeaders.length}} \{{?}} -{{~data.allHeaders :p:index}} -H '{{=p.name}}: {{=p.exampleValues.object}}'{{?index < data.allHeaders.length-1}} \{{?}} -{{~}} +{{~data.allHeaders :p:index}} -H '{{=p.name}}: {{=p.exampleValues.object}}'{{?index < data.allHeaders.length-1}} \ +{{?}}{{~}} diff --git a/scripts/apidocgen/markdown-template/operation.dot b/scripts/apidocgen/markdown-template/operation.dot index b33390ad4f3c5..f0363bcbabf45 100644 --- a/scripts/apidocgen/markdown-template/operation.dot +++ b/scripts/apidocgen/markdown-template/operation.dot @@ -1,3 +1,9 @@ +{{ + function renderCodeSample(data) { + const originalCodeSample = data.utils.getCodeSamples(data); + return originalCodeSample.replace("\n```\n", "```\n") + } +}} {{= data.tags.section }} ## {{= data.operationUniqueName}} @@ -14,7 +20,7 @@ {{? data.options.codeSamples || data.operation["x-code-samples"] }} ### Code samples -{{= data.utils.getCodeSamples(data)}} +{{=renderCodeSample(data)}} {{?}} `{{= data.methodUpper}} {{=data.method.path}}` From ef213acae97fc23e88b9ffe91d416172335d185f Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 14:46:55 +0100 Subject: [PATCH 17/28] More fixes --- coderd/apidoc/docs.go | 2 +- coderd/apidoc/swagger.json | 2 +- codersdk/authorization.go | 6 +++--- docs/api/applications.md | 6 +++--- docs/api/workspaces.md | 18 +++++++++--------- .../apidocgen/markdown-template/responses.def | 2 +- 6 files changed, 18 insertions(+), 18 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 6d4383dd24540..4cc2f31b9b564 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -744,7 +744,7 @@ const docTemplate = `{ ] }, "object": { - "description": "Object can represent a \"set\" of objects, such as:\n- All workspaces in an organization\n- All workspaces owned by me\n- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", + "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 8a110fd248a99..f08c130282126 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -648,7 +648,7 @@ "enum": ["create", "read", "update", "delete"] }, "object": { - "description": "Object can represent a \"set\" of objects, such as:\n- All workspaces in an organization\n- All workspaces owned by me\n- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", + "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.", "$ref": "#/definitions/codersdk.AuthorizationObject" } } diff --git a/codersdk/authorization.go b/codersdk/authorization.go index 64e9eeec3ff77..fffa50423f5b9 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -25,9 +25,9 @@ type AuthorizationRequest struct { // @Description AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. type AuthorizationCheck struct { // Object can represent a "set" of objects, such as: - // - All workspaces in an organization - // - All workspaces owned by me - // - All workspaces across the entire product + // - All workspaces in an organization + // - All workspaces owned by me + // - All workspaces across the entire product // When defining an object, use the most specific language when possible to // produce the smallest set. Meaning to set as many fields on 'Object' as // you can. Example, if you want to check if you can update all workspaces diff --git a/docs/api/applications.md b/docs/api/applications.md index fa283b4d02505..5c992955cb0ad 100644 --- a/docs/api/applications.md +++ b/docs/api/applications.md @@ -22,9 +22,9 @@ curl -X GET http://coder-server:8080/api/v2/applications/auth-redirect \ ### Responses -| Status | Meaning | Description | Schema | -| ------ | ----------------------------------------------------------------------- | ------------------ | --------- | -| 307 | [Temporary Redirect](https://tools.ietf.org/html/rfc7231#section-6.4.7) | Temporary Redirect | no schema | +| Status | Meaning | Description | Schema | +| ------ | ----------------------------------------------------------------------- | ------------------ | ------ | +| 307 | [Temporary Redirect](https://tools.ietf.org/html/rfc7231#section-6.4.7) | Temporary Redirect | | To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index f6fc0592a84be..70531c16652a7 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -707,9 +707,9 @@ curl -X PATCH http://coder-server:8080/api/v2/workspaces/{workspace} \ ### Responses -| Status | Meaning | Description | Schema | -| ------ | --------------------------------------------------------------- | ----------- | --------- | -| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | no schema | +| 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**. @@ -743,9 +743,9 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/autostart \ ### Responses -| Status | Meaning | Description | Schema | -| ------ | --------------------------------------------------------------- | ----------- | --------- | -| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | no schema | +| 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**. @@ -833,9 +833,9 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/ttl \ ### Responses -| Status | Meaning | Description | Schema | -| ------ | --------------------------------------------------------------- | ----------- | --------- | -| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | no schema | +| 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/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index b9d3c7c3b50be..7d31119093c89 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -6,7 +6,7 @@ break; } if (!content) { - return "no schema"; + return ""; } var ref = content.schema["x-widdershins-oldRef"]; From 12d904a03cfb1a177af8247518097543765b074e Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 15:24:41 +0100 Subject: [PATCH 18/28] Fix: br --- docs/api/schemas.md | 91 ++++++++++---------- scripts/apidocgen/markdown-template/main.dot | 5 +- 2 files changed, 49 insertions(+), 47 deletions(-) diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 1eb92eef76651..d0eecaf5738ed 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -49,12 +49,12 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ### Properties -| Name | Type | Required | Restrictions | Description | -| ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organization_id` | string | false | | Organization id (optional) adds the set constraint to all resources owned by a given organization. | -| `owner_id` | string | false | | Owner id (optional) adds the set constraint to all resources owned by a given user. | -| `resource_id` | string | false | | Resource id (optional) reduces the set to a singular resource. This assigns
a resource ID to the resource type, eg: a single workspace.
The rbac library will not fetch the resource from the database, so if you
are using this option, you should also set the `OwnerID` and `OrganizationID`
if possible. Be as specific as possible using all the fields relevant. | -| `resource_type` | string | false | | Resource type is the name of the resource.
`./coderd/rbac/object.go` has the list of valid resource types. | +| Name | Type | Required | Restrictions | Description | +| ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization_id` | string | false | | Organization id (optional) adds the set constraint to all resources owned by a given organization. | +| `owner_id` | string | false | | Owner id (optional) adds the set constraint to all resources owned by a given user. | +| `resource_id` | string | false | | Resource id (optional) reduces the set to a singular resource. This assigns a resource ID to the resource type, eg: a single workspace. The rbac library will not fetch the resource from the database, so if you are using this option, you should also set the `OwnerID` and `OrganizationID` if possible. Be as specific as possible using all the fields relevant. | +| `resource_type` | string | false | | Resource type is the name of the resource. `./coderd/rbac/object.go` has the list of valid resource types. | ## codersdk.AuthorizationRequest @@ -85,10 +85,10 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `checks` | object | false | | Checks is a map keyed with an arbitrary string to a permission check.
The key can be any string that is helpful to the caller, and allows
multiple permission checks to be run in a single request.
The key ensures that each permission check has the same key in the
response. | -| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | | It is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | +| Name | Type | Required | Restrictions | Description | +| ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `checks` | object | false | | Checks is a map keyed with an arbitrary string to a permission check. The key can be any string that is helpful to the caller, and allows multiple permission checks to be run in a single request. The key ensures that each permission check has the same key in the response. | +| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | | It is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. | ## codersdk.AuthorizationResponse @@ -121,13 +121,13 @@ CreateParameterRequest is a structure used to create a new parameter value for a ### Properties -| Name | Type | Required | Restrictions | Description | -| --------------------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `copy_from_parameter` | string | false | | Copy from parameter allows copying the value of another parameter.
The other param must be related to the same template_id for this to
succeed.
No other fields are required if using this, as all fields will be copied
from the other parameter. | -| `destination_scheme` | string | true | | | -| `name` | string | true | | | -| `source_scheme` | string | true | | | -| `source_value` | string | true | | | +| Name | Type | Required | Restrictions | Description | +| --------------------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `copy_from_parameter` | string | false | | Copy from parameter allows copying the value of another parameter. The other param must be related to the same template_id for this to succeed. No other fields are required if using this, as all fields will be copied from the other parameter. | +| `destination_scheme` | string | true | | | +| `name` | string | true | | | +| `source_scheme` | string | true | | | +| `source_value` | string | true | | | #### Enumerated Values @@ -162,16 +162,17 @@ CreateParameterRequest is a structure used to create a new parameter value for a ### Properties -| Name | Type | Required | Restrictions | Description | -| ---------------------------------- | --------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `allow_user_cancel_workspace_jobs` | boolean | false | | Allow users to cancel in-progress workspace jobs.
\*bool as the default value is "true". | -| `default_ttl_ms` | integer | false | | Default ttl ms allows optionally specifying the default TTL
for all workspaces created from this template. | -| `description` | string | false | | Description is a description of what the template contains. It must be
less than 128 bytes. | -| `display_name` | string | false | | Display name is the displayed name of the template. | -| `icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `name` | string | true | | Name is the name of the template. | -| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | | Parameter values is a structure used to create a new parameter value for a scope.] | -| `template_version_id` | string | true | | Template version id is an in-progress or completed job to use as an initial version
of the template.

This is required on creation to enable a user-flow of validating a
template works. There is no reason the data-model cannot support empty
templates, but it doesn't make sense for users. | +| Name | Type | Required | Restrictions | Description | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------- | +| `allow_user_cancel_workspace_jobs` | boolean | false | | Allow users to cancel in-progress workspace jobs. \*bool as the default value is "true". | +| `default_ttl_ms` | integer | false | | Default ttl ms allows optionally specifying the default TTL for all workspaces created from this template. | +| `description` | string | false | | Description is a description of what the template contains. It must be less than 128 bytes. | +| `display_name` | string | false | | Display name is the displayed name of the template. | +| `icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | +| `name` | string | true | | Name is the name of the template. | +| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | | Parameter values is a structure used to create a new parameter value for a scope.] | +| `template_version_id` | string | true | | Template version id is an in-progress or completed job to use as an initial version of the template. | +| This is required on creation to enable a user-flow of validating a template works. There is no reason the data-model cannot support empty templates, but it doesn't make sense for users. | ## codersdk.DERPRegion @@ -288,11 +289,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------- | ------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `detail` | string | false | | Detail is a debug message that provides further insight into why the
action failed. This information can be technical and a regular golang
err.Error() text.
- "database: too many open connections"
- "stat: too many open files" | -| `message` | string | false | | Message is an actionable message that depicts actions the request took.
These messages should be fully formed sentences with proper punctuation.
Examples:
- "A user has been created."
- "Failed to create a user." | -| `validations` | array of [codersdk.ValidationError](#codersdkvalidationerror) | false | | Validations are form field-specific friendly error messages. They will be
shown on a form field in the UI. These can also be used to add additional
context if there is a set of errors in the primary 'Message'. | +| Name | Type | Required | Restrictions | Description | +| ------------- | ------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `detail` | string | false | | Detail is a debug message that provides further insight into why the action failed. This information can be technical and a regular golang err.Error() text. - "database: too many open connections" - "stat: too many open files" | +| `message` | string | false | | Message is an actionable message that depicts actions the request took. These messages should be fully formed sentences with proper punctuation. Examples: - "A user has been created." - "Failed to create a user." | +| `validations` | array of [codersdk.ValidationError](#codersdkvalidationerror) | false | | Validations are form field-specific friendly error messages. They will be shown on a form field in the UI. These can also be used to add additional context if there is a set of errors in the primary 'Message'. | ## codersdk.Template @@ -706,19 +707,19 @@ CreateParameterRequest is a structure used to create a new parameter value for a ### Properties -| Name | Type | Required | Restrictions | Description | -| --------------- | -------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `command` | string | false | | | -| `display_name` | string | false | | Display name is a friendly name for the app. | -| `external` | boolean | false | | External specifies whether the URL should be opened externally on
the client or not. | -| `health` | string | false | | | -| `healthcheck` | [codersdk.Healthcheck](#codersdkhealthcheck) | false | | | -| `icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `id` | string | false | | | -| `sharing_level` | string | false | | | -| `slug` | string | false | | Slug is a unique identifier within the agent. | -| `subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | -| `url` | string | false | | Url is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | +| Name | Type | Required | Restrictions | Description | +| --------------- | -------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `command` | string | false | | | +| `display_name` | string | false | | Display name is a friendly name for the app. | +| `external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. | +| `health` | string | false | | | +| `healthcheck` | [codersdk.Healthcheck](#codersdkhealthcheck) | false | | | +| `icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | +| `id` | string | false | | | +| `sharing_level` | string | false | | | +| `slug` | string | false | | Slug is a unique identifier within the agent. | +| `subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. | +| `url` | string | false | | Url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | ## codersdk.WorkspaceBuild diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index 26df1e67855e2..c86d3570975e3 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -33,7 +33,8 @@ return ""; } - const words = p.description.split(' '); + const description = p.description.replaceAll("

", "\n").replaceAll("
", " "); + const words = description.split(' '); if (words.length == 0) { return ""; } @@ -44,7 +45,7 @@ displayName = displayName.charAt(0).toUpperCase() + displayName.replaceAll("_", " ").toLowerCase().slice(1); return displayName + " " + words.slice(1).join(' '); } - return p.description; + return description; } }} From f3e8c382431fbc10ee8ed8f67feb112d0a59cfe3 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 15:27:47 +0100 Subject: [PATCH 19/28] Merge --- docs/api/general.md | 10 +++------- docs/api/schemas.md | 20 ++++++++++---------- 2 files changed, 13 insertions(+), 17 deletions(-) diff --git a/docs/api/general.md b/docs/api/general.md index a17febec62cd6..83168de5ddabf 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -10,7 +10,6 @@ # Example request using curl curl -X GET http://coder-server:8080/api/v2/ \ -H 'Accept: application/json' - ``` `GET /` @@ -48,7 +47,6 @@ undefined # Example request using curl curl -X GET http://coder-server:8080/api/v2/buildinfo \ -H 'Accept: application/json' - ``` `GET /buildinfo` @@ -81,7 +79,6 @@ undefined curl -X POST http://coder-server:8080/api/v2/csp/reports \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `POST /csp/reports` @@ -102,9 +99,9 @@ curl -X POST http://coder-server:8080/api/v2/csp/reports \ ### Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------- | ----------- | --------- | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | no schema | +| 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**. @@ -117,7 +114,6 @@ To perform this operation, you must be authenticated by means of one of the foll curl -X GET http://coder-server:8080/api/v2/updatecheck \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' - ``` `GET /updatecheck` diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 3d45cce389c09..8a302cc303376 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -14,7 +14,7 @@ | Name | Type | Required | Restrictions | Description | | ------------ | ------ | -------- | ------------ | ----------- | -| `csp-report` | object | false | none | none | +| `csp-report` | object | false | | | ## codersdk.AuthorizationCheck @@ -130,10 +130,10 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ### Properties -| Name | Type | Required | Restrictions | Description | -| -------------- | ------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `external_url` | string | false | none | External url is a URL referencing the current Coder version. For production
builds, this will link directly to a release. For development builds, this
will link to a commit. | -| `version` | string | false | none | Version returns the semantic version of the build. | +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `external_url` | string | false | | External url is a URL referencing the current Coder version. For production builds, this will link directly to a release. For development builds, this will link to a commit. | +| `version` | string | false | | Version returns the semantic version of the build. | ## codersdk.CreateParameterRequest @@ -429,11 +429,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a ### Properties -| Name | Type | Required | Restrictions | Description | -| --------- | ------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | -| `current` | boolean | false | none | Current is a boolean indicating whether the
server version is the same as the latest. | -| `url` | string | false | none | Url to download the latest release of Coder. | -| `version` | string | false | none | Version is the semantic version for the latest
release of Coder. | +| Name | Type | Required | Restrictions | Description | +| --------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------- | +| `current` | boolean | false | | Current is a boolean indicating whether the server version is the same as the latest. | +| `url` | string | false | | Url to download the latest release of Coder. | +| `version` | string | false | | Version is the semantic version for the latest release of Coder. | ## codersdk.UpdateWorkspaceAutostartRequest From 0e0af2999275b133453fb979b2811a6c58c31788 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 16:31:33 +0100 Subject: [PATCH 20/28] Fix: no-security on updatecheck --- coderd/apidoc/docs.go | 5 ----- coderd/apidoc/swagger.json | 5 ----- coderd/updatecheck.go | 1 - docs/api/general.md | 5 ++--- 4 files changed, 2 insertions(+), 14 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index f7911a84e37ed..4adb9e4c83c88 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -430,11 +430,6 @@ const docTemplate = `{ }, "/updatecheck": { "get": { - "security": [ - { - "CoderSessionToken": [] - } - ], "produces": [ "application/json" ], diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 2f3d63e8e1085..0a8f9f61bb00d 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -370,11 +370,6 @@ }, "/updatecheck": { "get": { - "security": [ - { - "CoderSessionToken": [] - } - ], "produces": ["application/json"], "tags": ["General"], "summary": "Update check", diff --git a/coderd/updatecheck.go b/coderd/updatecheck.go index 2aa796fcd047e..882a5e6f4b5a2 100644 --- a/coderd/updatecheck.go +++ b/coderd/updatecheck.go @@ -15,7 +15,6 @@ import ( // @Summary Update check // @ID update-check -// @Security CoderSessionToken // @Produce json // @Tags General // @Success 200 {object} codersdk.UpdateCheckResponse diff --git a/docs/api/general.md b/docs/api/general.md index 83168de5ddabf..f173006204a3f 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -112,8 +112,7 @@ To perform this operation, you must be authenticated by means of one of the foll ```shell # Example request using curl curl -X GET http://coder-server:8080/api/v2/updatecheck \ - -H 'Accept: application/json' \ - -H 'Coder-Session-Token: API_KEY' + -H 'Accept: application/json' ``` `GET /updatecheck` @@ -136,4 +135,4 @@ curl -X GET http://coder-server:8080/api/v2/updatecheck \ | ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- | | 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.UpdateCheckResponse](schemas.md#codersdkupdatecheckresponse) | -To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. +undefined From ed6ed0af9057b8af4d9e9c78bfd05a81bf3aca01 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 16:34:29 +0100 Subject: [PATCH 21/28] Fix: code tags --- docs/api/applications.md | 6 +- docs/api/authorization.md | 6 +- docs/api/general.md | 6 +- docs/api/templates.md | 72 ++++++++--------- docs/api/workspaces.md | 78 +++++++++---------- .../markdown-template/parameters.def | 2 +- .../apidocgen/markdown-template/responses.def | 2 +- 7 files changed, 86 insertions(+), 86 deletions(-) diff --git a/docs/api/applications.md b/docs/api/applications.md index 5c992955cb0ad..eeb6f42c2c21d 100644 --- a/docs/api/applications.md +++ b/docs/api/applications.md @@ -16,9 +16,9 @@ curl -X GET http://coder-server:8080/api/v2/applications/auth-redirect \ ### Parameters -| Name | In | Type | Required | Description | -| ------------ | ----- | ------ | -------- | -------------------- | -| redirect_uri | query | string | false | Redirect destination | +| Name | In | Type | Required | Description | +| -------------- | ----- | ------ | -------- | -------------------- | +| `redirect_uri` | query | string | false | Redirect destination | ### Responses diff --git a/docs/api/authorization.md b/docs/api/authorization.md index 7fc0d08267399..e6c2e9e155a72 100644 --- a/docs/api/authorization.md +++ b/docs/api/authorization.md @@ -45,9 +45,9 @@ curl -X POST http://coder-server:8080/api/v2/authcheck \ ### Parameters -| Name | In | Type | Required | Description | -| ---- | ---- | ------------------------------------------------------------------------ | -------- | --------------------- | -| body | body | [codersdk.AuthorizationRequest](schemas.md#codersdkauthorizationrequest) | true | Authorization request | +| Name | In | Type | Required | Description | +| ------ | ---- | ------------------------------------------------------------------------ | -------- | --------------------- | +| `body` | body | [codersdk.AuthorizationRequest](schemas.md#codersdkauthorizationrequest) | true | Authorization request | ### Example responses diff --git a/docs/api/general.md b/docs/api/general.md index f173006204a3f..8d5ef5dad967d 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -93,9 +93,9 @@ curl -X POST http://coder-server:8080/api/v2/csp/reports \ ### Parameters -| Name | In | Type | Required | Description | -| ---- | ---- | ---------------------------------------------------- | -------- | ---------------- | -| body | body | [coderd.cspViolation](schemas.md#coderdcspviolation) | true | Violation report | +| Name | In | Type | Required | Description | +| ------ | ---- | ---------------------------------------------------- | -------- | ---------------- | +| `body` | body | [coderd.cspViolation](schemas.md#coderdcspviolation) | true | Violation report | ### Responses diff --git a/docs/api/templates.md b/docs/api/templates.md index 48301afd108f9..7e5c240da8f9d 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -41,10 +41,10 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization-id}/tem ### Parameters -| Name | In | Type | Required | Description | -| --------------- | ---- | -------------------------------------------------------------------------- | -------- | --------------- | -| organization-id | path | string | true | Organization ID | -| body | body | [codersdk.CreateTemplateRequest](schemas.md#codersdkcreatetemplaterequest) | true | Request body | +| Name | In | Type | Required | Description | +| ----------------- | ---- | -------------------------------------------------------------------------- | -------- | --------------- | +| `organization-id` | path | string | true | Organization ID | +| `body` | body | [codersdk.CreateTemplateRequest](schemas.md#codersdkcreatetemplaterequest) | true | Request body | ### Example responses @@ -104,9 +104,9 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat ### Parameters -| Name | In | Type | Required | Description | -| ------------ | ---- | ------------ | -------- | --------------- | -| organization | path | string(uuid) | true | Organization ID | +| Name | In | Type | Required | Description | +| -------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | ### Example responses @@ -155,29 +155,29 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat Status Code **200** -| Name | Type | Required | Restrictions | Description | -| ---------------------------------- | --------------------------------- | -------- | ------------ | ------------------------------------------ | -| _anonymous_ | array | false | | | -| » active_user_count | integer | false | | ActiveUserCount is set to -1 when loading. | -| » active_version_id | string | false | | | -| » allow_user_cancel_workspace_jobs | boolean | false | | | -| » build_time_stats | `codersdk.TemplateBuildTimeStats` | false | | | -| »» **additionalProperties** | `codersdk.TransitionStats` | false | | | -| »»» p50 | integer | false | | | -| »»» p95 | integer | false | | | -| » created_at | string | false | | | -| » created_by_id | string | false | | | -| » created_by_name | string | false | | | -| » default_ttl_ms | integer | false | | | -| » description | string | false | | | -| » display_name | string | false | | | -| » icon | string | false | | | -| » id | string | false | | | -| » name | string | false | | | -| » organization_id | string | false | | | -| » provisioner | string | false | | | -| » updated_at | string | false | | | -| » workspace_owner_count | integer | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------------------------ | --------------------------------- | -------- | ------------ | ------------------------------------------ | +| `*anonymous*` | array | false | | | +| `» active_user_count` | integer | false | | ActiveUserCount is set to -1 when loading. | +| `» active_version_id` | string | false | | | +| `» allow_user_cancel_workspace_jobs` | boolean | false | | | +| `» build_time_stats` | `codersdk.TemplateBuildTimeStats` | false | | | +| `»» **additionalProperties**` | `codersdk.TransitionStats` | false | | | +| `»»» p50` | integer | false | | | +| `»»» p95` | integer | false | | | +| `» created_at` | string | false | | | +| `» created_by_id` | string | false | | | +| `» created_by_name` | string | false | | | +| `» default_ttl_ms` | integer | false | | | +| `» description` | string | false | | | +| `» display_name` | string | false | | | +| `» icon` | string | false | | | +| `» id` | string | false | | | +| `» name` | string | false | | | +| `» organization_id` | string | false | | | +| `» provisioner` | string | false | | | +| `» updated_at` | string | false | | | +| `» workspace_owner_count` | integer | false | | | To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**. @@ -196,10 +196,10 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat ### Parameters -| Name | In | Type | Required | Description | -| ------------- | ---- | ------------ | -------- | --------------- | -| organization | path | string(uuid) | true | Organization ID | -| template-name | path | string | true | Template name | +| Name | In | Type | Required | Description | +| --------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | +| `template-name` | path | string | true | Template name | ### Example responses @@ -261,7 +261,7 @@ curl -X GET http://coder-server:8080/api/v2/templates/{id} \ | Name | In | Type | Required | Description | | ---- | ---- | ------------ | -------- | ----------- | -| id | path | string(uuid) | true | Template ID | +| `id` | path | string(uuid) | true | Template ID | ### Example responses @@ -323,7 +323,7 @@ curl -X DELETE http://coder-server:8080/api/v2/templates/{id} \ | Name | In | Type | Required | Description | | ---- | ---- | ------------ | -------- | ----------- | -| id | path | string(uuid) | true | Template ID | +| `id` | path | string(uuid) | true | Template ID | ### Example responses diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index 70531c16652a7..9002dc9ccc397 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -17,10 +17,10 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/member ### Parameters -| Name | In | Type | Required | Description | -| ------------ | ---- | ------------ | -------- | --------------- | -| organization | path | string(uuid) | true | Organization ID | -| user | path | string | true | Username | +| Name | In | Type | Required | Description | +| -------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | +| `user` | path | string | true | Username | ### Example responses @@ -180,11 +180,11 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacenam ### Parameters -| Name | In | Type | Required | Description | -| --------------- | ----- | ------- | -------- | ----------------------------------------------------------- | -| user | path | string | true | Owner username | -| workspacename | path | string | true | Workspace name | -| include_deleted | query | boolean | false | Return data instead of HTTP 404 if the workspace is deleted | +| Name | In | Type | Required | Description | +| ----------------- | ----- | ------- | -------- | ----------------------------------------------------------- | +| `user` | path | string | true | Owner username | +| `workspacename` | path | string | true | Workspace name | +| `include_deleted` | query | boolean | false | Return data instead of HTTP 404 if the workspace is deleted | ### Example responses @@ -344,13 +344,13 @@ curl -X GET http://coder-server:8080/api/v2/workspaces \ ### Parameters -| Name | In | Type | Required | Description | -| --------- | ----- | ------ | -------- | ------------------------------------------- | -| owner | query | string | false | Filter by owner username | -| template | query | string | false | Filter by template name | -| name | query | string | false | Filter with partial-match by workspace name | -| status | query | string | false | Filter by workspace status | -| has_agent | query | string | false | Filter by agent status | +| Name | In | Type | Required | Description | +| ----------- | ----- | ------ | -------- | ------------------------------------------- | +| `owner` | query | string | false | Filter by owner username | +| `template` | query | string | false | Filter by template name | +| `name` | query | string | false | Filter with partial-match by workspace name | +| `status` | query | string | false | Filter by workspace status | +| `has_agent` | query | string | false | Filter by agent status | #### Enumerated Values @@ -529,10 +529,10 @@ curl -X GET http://coder-server:8080/api/v2/workspaces/{id} \ ### Parameters -| Name | In | Type | Required | Description | -| --------------- | ----- | ------------ | -------- | ----------------------------------------------------------- | -| id | path | string(uuid) | true | Workspace ID | -| include_deleted | query | boolean | false | Return data instead of HTTP 404 if the workspace is deleted | +| Name | In | Type | Required | Description | +| ----------------- | ----- | ------------ | -------- | ----------------------------------------------------------- | +| `id` | path | string(uuid) | true | Workspace ID | +| `include_deleted` | query | boolean | false | Return data instead of HTTP 404 if the workspace is deleted | ### Example responses @@ -700,10 +700,10 @@ curl -X PATCH http://coder-server:8080/api/v2/workspaces/{workspace} \ ### Parameters -| Name | In | Type | Required | Description | -| --------- | ---- | ---------------------------------------------------------------------------- | -------- | ----------------------- | -| workspace | path | string(uuid) | true | Workspace ID | -| body | body | [codersdk.UpdateWorkspaceRequest](schemas.md#codersdkupdateworkspacerequest) | true | Metadata update request | +| Name | In | Type | Required | Description | +| ----------- | ---- | ---------------------------------------------------------------------------- | -------- | ----------------------- | +| `workspace` | path | string(uuid) | true | Workspace ID | +| `body` | body | [codersdk.UpdateWorkspaceRequest](schemas.md#codersdkupdateworkspacerequest) | true | Metadata update request | ### Responses @@ -736,10 +736,10 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/autostart \ ### Parameters -| Name | In | Type | Required | Description | -| --------- | ---- | ---------------------------------------------------------------------------------------------- | -------- | ----------------------- | -| workspace | path | string(uuid) | true | Workspace ID | -| body | body | [codersdk.UpdateWorkspaceAutostartRequest](schemas.md#codersdkupdateworkspaceautostartrequest) | true | Schedule update request | +| Name | In | Type | Required | Description | +| ----------- | ---- | ---------------------------------------------------------------------------------------------- | -------- | ----------------------- | +| `workspace` | path | string(uuid) | true | Workspace ID | +| `body` | body | [codersdk.UpdateWorkspaceAutostartRequest](schemas.md#codersdkupdateworkspaceautostartrequest) | true | Schedule update request | ### Responses @@ -773,10 +773,10 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/extend \ ### Parameters -| Name | In | Type | Required | Description | -| --------- | ---- | ---------------------------------------------------------------------------------- | -------- | ------------------------------ | -| workspace | path | string(uuid) | true | Workspace ID | -| body | body | [codersdk.PutExtendWorkspaceRequest](schemas.md#codersdkputextendworkspacerequest) | true | Extend deadline update request | +| Name | In | Type | Required | Description | +| ----------- | ---- | ---------------------------------------------------------------------------------- | -------- | ------------------------------ | +| `workspace` | path | string(uuid) | true | Workspace ID | +| `body` | body | [codersdk.PutExtendWorkspaceRequest](schemas.md#codersdkputextendworkspacerequest) | true | Extend deadline update request | ### Example responses @@ -826,10 +826,10 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/ttl \ ### Parameters -| Name | In | Type | Required | Description | -| --------- | ---- | ---------------------------------------------------------------------------------- | -------- | ---------------------------- | -| workspace | path | string(uuid) | true | Workspace ID | -| body | body | [codersdk.UpdateWorkspaceTTLRequest](schemas.md#codersdkupdateworkspacettlrequest) | true | Workspace TTL update request | +| Name | In | Type | Required | Description | +| ----------- | ---- | ---------------------------------------------------------------------------------- | -------- | ---------------------------- | +| `workspace` | path | string(uuid) | true | Workspace ID | +| `body` | body | [codersdk.UpdateWorkspaceTTLRequest](schemas.md#codersdkupdateworkspacettlrequest) | true | Workspace TTL update request | ### Responses @@ -854,9 +854,9 @@ curl -X GET http://coder-server:8080/api/v2/workspaces/{workspace}/watch \ ### Parameters -| Name | In | Type | Required | Description | -| --------- | ---- | ------------ | -------- | ------------ | -| workspace | path | string(uuid) | true | Workspace ID | +| Name | In | Type | Required | Description | +| ----------- | ---- | ------------ | -------- | ------------ | +| `workspace` | path | string(uuid) | true | Workspace ID | ### Example responses diff --git a/scripts/apidocgen/markdown-template/parameters.def b/scripts/apidocgen/markdown-template/parameters.def index 1b00563cb37f4..b049c894b7151 100644 --- a/scripts/apidocgen/markdown-template/parameters.def +++ b/scripts/apidocgen/markdown-template/parameters.def @@ -13,7 +13,7 @@ |Name|In|Type|Required|Description| |---|---|---|---|---| -{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{= renderParameterType(p)}}|{{=p.required}}|{{=p.shortDesc||''}}| +{{~ data.parameters :p}}|`{{=p.name}}`|{{=p.in}}|{{= renderParameterType(p)}}|{{=p.required}}|{{=p.shortDesc||''}}| {{~}} {{? data.longDescs }} diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index 7d31119093c89..7b8b3f197a14f 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -77,7 +77,7 @@ Status Code **{{=response.status}}** {{?}} |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| -{{~block.rows :p}}|{{=p.displayName}}|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}| +{{~block.rows :p}}|`{{=p.displayName}}`|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}| {{~}} {{~}} {{?}} From 6c6c509b8e9ee80bc0b68072ed12550dbf5e3b28 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 16:37:26 +0100 Subject: [PATCH 22/28] Fix: enumerated values in code tags --- docs/api/schemas.md | 62 +++++++++---------- docs/api/workspaces.md | 30 ++++----- scripts/apidocgen/markdown-template/main.dot | 2 +- .../markdown-template/parameters.def | 2 +- .../apidocgen/markdown-template/responses.def | 2 +- 5 files changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 8a302cc303376..b89ee6da2ddca 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -41,12 +41,12 @@ AuthorizationCheck is used to check if the currently authenticated user (or the #### Enumerated Values -| Property | Value | -| -------- | ------ | -| action | create | -| action | read | -| action | update | -| action | delete | +| Property | Value | +| -------- | -------- | +| `action` | `create` | +| `action` | `read` | +| `action` | `update` | +| `action` | `delete` | ## codersdk.AuthorizationObject @@ -161,11 +161,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a #### Enumerated Values -| Property | Value | -| ------------------ | -------------------- | -| destination_scheme | environment_variable | -| destination_scheme | provisioner_variable | -| source_scheme | data | +| Property | Value | +| -------------------- | ---------------------- | +| `destination_scheme` | `environment_variable` | +| `destination_scheme` | `provisioner_variable` | +| `source_scheme` | `data` | ## codersdk.CreateTemplateRequest @@ -911,21 +911,21 @@ CreateParameterRequest is a structure used to create a new parameter value for a #### Enumerated Values -| Property | Value | -| ---------- | --------- | -| status | pending | -| status | starting | -| status | running | -| status | stopping | -| status | stopped | -| status | failed | -| status | canceling | -| status | canceled | -| status | deleting | -| status | deleted | -| transition | start | -| transition | stop | -| transition | delete | +| Property | Value | +| ------------ | ----------- | +| `status` | `pending` | +| `status` | `starting` | +| `status` | `running` | +| `status` | `stopping` | +| `status` | `stopped` | +| `status` | `failed` | +| `status` | `canceling` | +| `status` | `canceled` | +| `status` | `deleting` | +| `status` | `deleted` | +| `transition` | `start` | +| `transition` | `stop` | +| `transition` | `delete` | ## codersdk.WorkspaceResource @@ -1022,11 +1022,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a #### Enumerated Values -| Property | Value | -| -------------------- | ------ | -| workspace_transition | start | -| workspace_transition | stop | -| workspace_transition | delete | +| Property | Value | +| ---------------------- | -------- | +| `workspace_transition` | `start` | +| `workspace_transition` | `stop` | +| `workspace_transition` | `delete` | ## codersdk.WorkspaceResourceMetadata diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index 9002dc9ccc397..fcbfcda60d60e 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -354,21 +354,21 @@ curl -X GET http://coder-server:8080/api/v2/workspaces \ #### Enumerated Values -| Parameter | Value | -| --------- | ------------ | -| status | pending | -| status | running | -| status | stopping | -| status | stopped | -| status | failed | -| status | canceling | -| status | canceled | -| status | deleted | -| status | deleting | -| has_agent | connected | -| has_agent | connecting | -| has_agent | disconnected | -| has_agent | timeout | +| Parameter | Value | +| ----------- | -------------- | +| `status` | `pending` | +| `status` | `running` | +| `status` | `stopping` | +| `status` | `stopped` | +| `status` | `failed` | +| `status` | `canceling` | +| `status` | `canceled` | +| `status` | `deleted` | +| `status` | `deleting` | +| `has_agent` | `connected` | +| `has_agent` | `connecting` | +| `has_agent` | `disconnected` | +| `has_agent` | `timeout` | ### Example responses diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index c86d3570975e3..4629598e14c5e 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -140,7 +140,7 @@ |Property|Value| |---|---| -{{~ enums :e}}|{{=e.name}}|{{=data.utils.toPrimitive(e.value)}}| +{{~ enums :e}}|`{{=e.name}}`|`{{=data.utils.toPrimitive(e.value)}}`| {{~}} {{= data.tags.endSection }} diff --git a/scripts/apidocgen/markdown-template/parameters.def b/scripts/apidocgen/markdown-template/parameters.def index b049c894b7151..47d81bd3d1863 100644 --- a/scripts/apidocgen/markdown-template/parameters.def +++ b/scripts/apidocgen/markdown-template/parameters.def @@ -44,7 +44,7 @@ |Parameter|Value| |---|---| -{{~ data.enums :e}}|{{=e.name}}|{{=data.utils.toPrimitive(e.value)}}| +{{~ data.enums :e}}|`{{=e.name}}`|`{{=data.utils.toPrimitive(e.value)}}`| {{~}} {{?}} {{= data.tags.endSection }} diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index 7b8b3f197a14f..ca906d38d299a 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -87,7 +87,7 @@ Status Code **{{=response.status}}** |Property|Value| |---|---| -{{~ enums :e}}|{{=e.name}}|{{=data.utils.toPrimitive(e.value)}}| +{{~ enums :e}}|`{{=e.name}}`|`{{=data.utils.toPrimitive(e.value)}}`| {{~}} {{?}} From 59de7a032b2258f0660c9587decbeffb95666410 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 21 Dec 2022 19:16:44 +0100 Subject: [PATCH 23/28] Rephrased --- coderd/apidoc/docs.go | 6 +++--- coderd/apidoc/swagger.json | 6 +++--- codersdk/buildinfo.go | 5 ++--- codersdk/updatecheck.go | 12 ++++-------- docs/api/schemas.md | 10 +++++----- 5 files changed, 17 insertions(+), 22 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 4adb9e4c83c88..6cf637c960421 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -898,7 +898,7 @@ const docTemplate = `{ "type": "object", "properties": { "external_url": { - "description": "ExternalURL is a URL referencing the current Coder version. For production\nbuilds, this will link directly to a release. For development builds, this\nwill link to a commit.", + "description": "ExternalURL is a URL referencing the current Coder version.\nFor production builds, this will link directly to a release. For development builds, this will link to a commit.", "type": "string" }, "version": { @@ -1188,7 +1188,7 @@ const docTemplate = `{ "type": "object", "properties": { "current": { - "description": "Current is a boolean indicating whether the\nserver version is the same as the latest.", + "description": "Current indicates whether the server version is the same as the latest.", "type": "boolean" }, "url": { @@ -1196,7 +1196,7 @@ const docTemplate = `{ "type": "string" }, "version": { - "description": "Version is the semantic version for the latest\nrelease of Coder.", + "description": "Version is the semantic version for the latest release of Coder.", "type": "string" } } diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 0a8f9f61bb00d..5ea162ef9c73c 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -784,7 +784,7 @@ "type": "object", "properties": { "external_url": { - "description": "ExternalURL is a URL referencing the current Coder version. For production\nbuilds, this will link directly to a release. For development builds, this\nwill link to a commit.", + "description": "ExternalURL is a URL referencing the current Coder version.\nFor production builds, this will link directly to a release. For development builds, this will link to a commit.", "type": "string" }, "version": { @@ -1064,7 +1064,7 @@ "type": "object", "properties": { "current": { - "description": "Current is a boolean indicating whether the\nserver version is the same as the latest.", + "description": "Current indicates whether the server version is the same as the latest.", "type": "boolean" }, "url": { @@ -1072,7 +1072,7 @@ "type": "string" }, "version": { - "description": "Version is the semantic version for the latest\nrelease of Coder.", + "description": "Version is the semantic version for the latest release of Coder.", "type": "string" } } diff --git a/codersdk/buildinfo.go b/codersdk/buildinfo.go index a8ba01e3716cb..5ce61dd133de2 100644 --- a/codersdk/buildinfo.go +++ b/codersdk/buildinfo.go @@ -11,9 +11,8 @@ import ( // BuildInfoResponse contains build information for this instance of Coder. type BuildInfoResponse struct { - // ExternalURL is a URL referencing the current Coder version. For production - // builds, this will link directly to a release. For development builds, this - // will link to a commit. + // ExternalURL is a URL referencing the current Coder version. + // For production builds, this will link directly to a release. For development builds, this will link to a commit. ExternalURL string `json:"external_url"` // Version returns the semantic version of the build. Version string `json:"version"` diff --git a/codersdk/updatecheck.go b/codersdk/updatecheck.go index 21da7ee309070..4f594e6acf0e1 100644 --- a/codersdk/updatecheck.go +++ b/codersdk/updatecheck.go @@ -6,21 +6,17 @@ import ( "net/http" ) -// UpdateCheckResponse contains information -// on the latest release of Coder. +// UpdateCheckResponse contains information on the latest release of Coder. type UpdateCheckResponse struct { - // Current is a boolean indicating whether the - // server version is the same as the latest. + // Current indicates whether the server version is the same as the latest. Current bool `json:"current"` - // Version is the semantic version for the latest - // release of Coder. + // Version is the semantic version for the latest release of Coder. Version string `json:"version"` // URL to download the latest release of Coder. URL string `json:"url"` } -// UpdateCheck returns information about the latest release version of -// Coder and whether or not the server is running the latest release. +// UpdateCheck returns information about the latest release version of Coder and whether or not the server is running the latest release. func (c *Client) UpdateCheck(ctx context.Context) (UpdateCheckResponse, error) { res, err := c.Request(ctx, http.MethodGet, "/api/v2/updatecheck", nil) if err != nil { diff --git a/docs/api/schemas.md b/docs/api/schemas.md index b89ee6da2ddca..3423cf1f9ee41 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -429,11 +429,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a ### Properties -| Name | Type | Required | Restrictions | Description | -| --------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------- | -| `current` | boolean | false | | Current is a boolean indicating whether the server version is the same as the latest. | -| `url` | string | false | | Url to download the latest release of Coder. | -| `version` | string | false | | Version is the semantic version for the latest release of Coder. | +| Name | Type | Required | Restrictions | Description | +| --------- | ------- | -------- | ------------ | ----------------------------------------------------------------------- | +| `current` | boolean | false | | Current indicates whether the server version is the same as the latest. | +| `url` | string | false | | Url to download the latest release of Coder. | +| `version` | string | false | | Version is the semantic version for the latest release of Coder. | ## codersdk.UpdateWorkspaceAutostartRequest From 171a675e20540796adfded53862090b800650d52 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Thu, 22 Dec 2022 08:55:01 +0100 Subject: [PATCH 24/28] Address PR comments --- coderd/csp.go | 4 ++-- codersdk/updatecheck.go | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/coderd/csp.go b/coderd/csp.go index 45cc65b450b64..ae3a0cbd99f93 100644 --- a/coderd/csp.go +++ b/coderd/csp.go @@ -14,6 +14,8 @@ type cspViolation struct { Report map[string]interface{} `json:"csp-report"` } +// logReportCSPViolations will log all reported csp violations. +// // @Summary Report CSP violations // @ID report-csp-violations // @Security CoderSessionToken @@ -23,8 +25,6 @@ type cspViolation struct { // @Param request body cspViolation true "Violation report" // @Success 200 // @Router /csp/reports [post] -// -// logReportCSPViolations will log all reported csp violations. func (api *API) logReportCSPViolations(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() var v cspViolation diff --git a/codersdk/updatecheck.go b/codersdk/updatecheck.go index 4f594e6acf0e1..25f6bfc96e840 100644 --- a/codersdk/updatecheck.go +++ b/codersdk/updatecheck.go @@ -16,7 +16,8 @@ type UpdateCheckResponse struct { URL string `json:"url"` } -// UpdateCheck returns information about the latest release version of Coder and whether or not the server is running the latest release. +// UpdateCheck returns information about the latest release version of +// Coder and whether or not the server is running the latest release. func (c *Client) UpdateCheck(ctx context.Context) (UpdateCheckResponse, error) { res, err := c.Request(ctx, http.MethodGet, "/api/v2/updatecheck", nil) if err != nil { From c831dc33eb6cd7f7e996b10a59d54e335a5212ae Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Thu, 22 Dec 2022 09:53:05 +0100 Subject: [PATCH 25/28] Fix: URL, id --- coderd/apidoc/docs.go | 6 ++--- coderd/apidoc/swagger.json | 6 ++--- codersdk/authorization.go | 2 +- codersdk/buildinfo.go | 2 +- codersdk/workspaceapps.go | 2 +- docs/api/schemas.md | 28 ++++++++++---------- scripts/apidocgen/markdown-template/main.dot | 21 ++++++++++++--- 7 files changed, 41 insertions(+), 26 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 6cf637c960421..e674cf6222bdd 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -867,7 +867,7 @@ const docTemplate = `{ "type": "string" }, "resource_id": { - "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the ` + "`" + `OwnerID` + "`" + ` and ` + "`" + `OrganizationID` + "`" + `\nif possible. Be as specific as possible using all the fields relevant.", + "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the owner ID and organization ID\nif possible. Be as specific as possible using all the fields relevant.", "type": "string" }, "resource_type": { @@ -898,7 +898,7 @@ const docTemplate = `{ "type": "object", "properties": { "external_url": { - "description": "ExternalURL is a URL referencing the current Coder version.\nFor production builds, this will link directly to a release. For development builds, this will link to a commit.", + "description": "ExternalURL references the current Coder version.\nFor production builds, this will link directly to a release. For development builds, this will link to a commit.", "type": "string" }, "version": { @@ -1017,7 +1017,7 @@ const docTemplate = `{ "type": "integer" }, "url": { - "description": "URL specifies the url to check for the app health.", + "description": "URL specifies the endpoint to check for the app health.", "type": "string" } } diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 5ea162ef9c73c..f33bec806f70a 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -753,7 +753,7 @@ "type": "string" }, "resource_id": { - "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the `OwnerID` and `OrganizationID`\nif possible. Be as specific as possible using all the fields relevant.", + "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the owner ID and organization ID\nif possible. Be as specific as possible using all the fields relevant.", "type": "string" }, "resource_type": { @@ -784,7 +784,7 @@ "type": "object", "properties": { "external_url": { - "description": "ExternalURL is a URL referencing the current Coder version.\nFor production builds, this will link directly to a release. For development builds, this will link to a commit.", + "description": "ExternalURL references the current Coder version.\nFor production builds, this will link directly to a release. For development builds, this will link to a commit.", "type": "string" }, "version": { @@ -895,7 +895,7 @@ "type": "integer" }, "url": { - "description": "URL specifies the url to check for the app health.", + "description": "URL specifies the endpoint to check for the app health.", "type": "string" } } diff --git a/codersdk/authorization.go b/codersdk/authorization.go index fffa50423f5b9..21b3f74ad84fa 100644 --- a/codersdk/authorization.go +++ b/codersdk/authorization.go @@ -54,7 +54,7 @@ type AuthorizationObject struct { // ResourceID (optional) reduces the set to a singular resource. This assigns // a resource ID to the resource type, eg: a single workspace. // The rbac library will not fetch the resource from the database, so if you - // are using this option, you should also set the `OwnerID` and `OrganizationID` + // are using this option, you should also set the owner ID and organization ID // if possible. Be as specific as possible using all the fields relevant. ResourceID string `json:"resource_id,omitempty"` } diff --git a/codersdk/buildinfo.go b/codersdk/buildinfo.go index 5ce61dd133de2..19c7f21910ab3 100644 --- a/codersdk/buildinfo.go +++ b/codersdk/buildinfo.go @@ -11,7 +11,7 @@ import ( // BuildInfoResponse contains build information for this instance of Coder. type BuildInfoResponse struct { - // ExternalURL is a URL referencing the current Coder version. + // ExternalURL references the current Coder version. // For production builds, this will link directly to a release. For development builds, this will link to a commit. ExternalURL string `json:"external_url"` // Version returns the semantic version of the build. diff --git a/codersdk/workspaceapps.go b/codersdk/workspaceapps.go index 3b9696e4c2a78..8f6003b5fae48 100644 --- a/codersdk/workspaceapps.go +++ b/codersdk/workspaceapps.go @@ -49,7 +49,7 @@ type WorkspaceApp struct { } type Healthcheck struct { - // URL specifies the url to check for the app health. + // URL specifies the endpoint to check for the app health. URL string `json:"url"` // Interval specifies the seconds between each health check. Interval int32 `json:"interval"` diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 3423cf1f9ee41..601a1fc7a396a 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -63,12 +63,12 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ### Properties -| Name | Type | Required | Restrictions | Description | -| ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organization_id` | string | false | | Organization id (optional) adds the set constraint to all resources owned by a given organization. | -| `owner_id` | string | false | | Owner id (optional) adds the set constraint to all resources owned by a given user. | -| `resource_id` | string | false | | Resource id (optional) reduces the set to a singular resource. This assigns a resource ID to the resource type, eg: a single workspace. The rbac library will not fetch the resource from the database, so if you are using this option, you should also set the `OwnerID` and `OrganizationID` if possible. Be as specific as possible using all the fields relevant. | -| `resource_type` | string | false | | Resource type is the name of the resource. `./coderd/rbac/object.go` has the list of valid resource types. | +| Name | Type | Required | Restrictions | Description | +| ----------------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization_id` | string | false | | Organization ID (optional) adds the set constraint to all resources owned by a given organization. | +| `owner_id` | string | false | | Owner ID (optional) adds the set constraint to all resources owned by a given user. | +| `resource_id` | string | false | | Resource ID (optional) reduces the set to a singular resource. This assigns a resource ID to the resource type, eg: a single workspace. The rbac library will not fetch the resource from the database, so if you are using this option, you should also set the owner ID and organization ID if possible. Be as specific as possible using all the fields relevant. | +| `resource_type` | string | false | | Resource type is the name of the resource. `./coderd/rbac/object.go` has the list of valid resource types. | ## codersdk.AuthorizationRequest @@ -130,10 +130,10 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ### Properties -| Name | Type | Required | Restrictions | Description | -| -------------- | ------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `external_url` | string | false | | External url is a URL referencing the current Coder version. For production builds, this will link directly to a release. For development builds, this will link to a commit. | -| `version` | string | false | | Version returns the semantic version of the build. | +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `external_url` | string | false | | External URL references the current Coder version. For production builds, this will link directly to a release. For development builds, this will link to a commit. | +| `version` | string | false | | Version returns the semantic version of the build. | ## codersdk.CreateParameterRequest @@ -201,7 +201,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | `icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | | `name` | string | true | | Name is the name of the template. | | `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | | Parameter values is a structure used to create a new parameter value for a scope.] | -| `template_version_id` | string | true | | Template version id is an in-progress or completed job to use as an initial version of the template. | +| `template_version_id` | string | true | | Template version ID is an in-progress or completed job to use as an initial version of the template. | | This is required on creation to enable a user-flow of validating a template works. There is no reason the data-model cannot support empty templates, but it doesn't make sense for users. | ## codersdk.DERPRegion @@ -250,7 +250,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | ----------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------ | | `interval` | integer | false | | Interval specifies the seconds between each health check. | | `threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | -| `url` | string | false | | Url specifies the url to check for the app health. | +| `url` | string | false | | URL specifies the endpoint to check for the app health. | ## codersdk.ProvisionerJob @@ -432,7 +432,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | Name | Type | Required | Restrictions | Description | | --------- | ------- | -------- | ------------ | ----------------------------------------------------------------------- | | `current` | boolean | false | | Current indicates whether the server version is the same as the latest. | -| `url` | string | false | | Url to download the latest release of Coder. | +| `url` | string | false | | URL to download the latest release of Coder. | | `version` | string | false | | Version is the semantic version for the latest release of Coder. | ## codersdk.UpdateWorkspaceAutostartRequest @@ -767,7 +767,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a | `sharing_level` | string | false | | | | `slug` | string | false | | Slug is a unique identifier within the agent. | | `subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. | -| `url` | string | false | | Url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | +| `url` | string | false | | URL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | ## codersdk.WorkspaceBuild diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index 4629598e14c5e..d040a95fa4490 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -28,12 +28,27 @@ return "`" + p.displayName + "`"; } + function correctLetterCase(description) { + const dictionary = ["id", "url"]; + + const words = description.split(' '); + var corrected = []; + words.forEach(word => { + if (dictionary.includes(word.toLowerCase())) { + corrected.push(word.toUpperCase()); + return; + } + corrected.push(word); + }); + return corrected.join(" "); + } + function renderDescription(p) { if (!p.description) { return ""; } - const description = p.description.replaceAll("

", "\n").replaceAll("
", " "); + let description = p.description.replaceAll("

", "\n").replaceAll("
", " "); const words = description.split(' '); if (words.length == 0) { return ""; @@ -43,9 +58,9 @@ if (countUppercase > 1) { let displayName = p.displayName.replaceAll("» **additionalProperties**", "It"); displayName = displayName.charAt(0).toUpperCase() + displayName.replaceAll("_", " ").toLowerCase().slice(1); - return displayName + " " + words.slice(1).join(' '); + description = displayName + " " + words.slice(1).join(' '); } - return description; + return correctLetterCase(description); } }} From 95c7760caac8e1c166c3f6acd9db7e55d0992300 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Thu, 22 Dec 2022 10:38:04 +0100 Subject: [PATCH 26/28] Fix: array items --- docs/api/templates.md | 2 +- scripts/apidocgen/markdown-template/responses.def | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/api/templates.md b/docs/api/templates.md index 7e5c240da8f9d..3f2a45b68142b 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -157,7 +157,7 @@ Status Code **200** | Name | Type | Required | Restrictions | Description | | ------------------------------------ | --------------------------------- | -------- | ------------ | ------------------------------------------ | -| `*anonymous*` | array | false | | | +| `[array items]` | array | false | | | | `» active_user_count` | integer | false | | ActiveUserCount is set to -1 when loading. | | `» active_version_id` | string | false | | | | `» allow_user_cancel_workspace_jobs` | boolean | false | | | diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index ca906d38d299a..cae21d077c081 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -24,6 +24,13 @@ } return renderSingleResponseType(r); } + + function renderDisplayName(p) { + if (p.displayName == "*anonymous*") { + return "[array items]"; + } + return p.displayName; + } }} {{ data.responses = data.utils.getResponses(data); }} {{ data.responseSchemas = false; }} @@ -77,7 +84,7 @@ Status Code **{{=response.status}}** {{?}} |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| -{{~block.rows :p}}|`{{=p.displayName}}`|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}| +{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}| {{~}} {{~}} {{?}} From 234f1402c0ec04d958a13a2f4d006c6dcac18f13 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Thu, 22 Dec 2022 10:43:44 +0100 Subject: [PATCH 27/28] Fix: any property --- docs/api/templates.md | 2 +- scripts/apidocgen/markdown-template/responses.def | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api/templates.md b/docs/api/templates.md index 3f2a45b68142b..73cee63508224 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -162,7 +162,7 @@ Status Code **200** | `» active_version_id` | string | false | | | | `» allow_user_cancel_workspace_jobs` | boolean | false | | | | `» build_time_stats` | `codersdk.TemplateBuildTimeStats` | false | | | -| `»» **additionalProperties**` | `codersdk.TransitionStats` | false | | | +| `»» [any property]` | `codersdk.TransitionStats` | false | | | | `»»» p50` | integer | false | | | | `»»» p95` | integer | false | | | | `» created_at` | string | false | | | diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index cae21d077c081..4291a879039ed 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -29,7 +29,8 @@ if (p.displayName == "*anonymous*") { return "[array items]"; } - return p.displayName; + let displayName = p.displayName.replace("**additionalProperties**", "[any property]"); + return displayName; } }} {{ data.responses = data.utils.getResponses(data); }} From 18b38c4f125946c71a44d26f21ca0bd183c616f2 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Thu, 22 Dec 2022 11:41:42 +0100 Subject: [PATCH 28/28] Fix: array item singular --- docs/api/templates.md | 2 +- scripts/apidocgen/markdown-template/responses.def | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/templates.md b/docs/api/templates.md index 73cee63508224..23a7260494db6 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -157,7 +157,7 @@ Status Code **200** | Name | Type | Required | Restrictions | Description | | ------------------------------------ | --------------------------------- | -------- | ------------ | ------------------------------------------ | -| `[array items]` | array | false | | | +| `[array item]` | array | false | | | | `» active_user_count` | integer | false | | ActiveUserCount is set to -1 when loading. | | `» active_version_id` | string | false | | | | `» allow_user_cancel_workspace_jobs` | boolean | false | | | diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index 4291a879039ed..426d10227ccd3 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -27,7 +27,7 @@ function renderDisplayName(p) { if (p.displayName == "*anonymous*") { - return "[array items]"; + return "[array item]"; } let displayName = p.displayName.replace("**additionalProperties**", "[any property]"); return displayName;