diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
index 4cc2f31b9b564..e674cf6222bdd 100644
--- a/coderd/apidoc/docs.go
+++ b/coderd/apidoc/docs.go
@@ -25,6 +25,26 @@ const docTemplate = `{
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
+ "/": {
+ "get": {
+ "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 +136,62 @@ const docTemplate = `{
}
}
},
+ "/buildinfo": {
+ "get": {
+ "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": [
@@ -352,6 +428,26 @@ const docTemplate = `{
}
}
},
+ "/updatecheck": {
+ "get": {
+ "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": [
@@ -730,6 +826,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",
@@ -762,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": {
@@ -789,6 +894,19 @@ const docTemplate = `{
"type": "boolean"
}
},
+ "codersdk.BuildInfoResponse": {
+ "type": "object",
+ "properties": {
+ "external_url": {
+ "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": {
+ "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",
@@ -899,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"
}
}
@@ -1066,6 +1184,23 @@ const docTemplate = `{
}
}
},
+ "codersdk.UpdateCheckResponse": {
+ "type": "object",
+ "properties": {
+ "current": {
+ "description": "Current indicates whether the server 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 release of Coder.",
+ "type": "string"
+ }
+ }
+ },
"codersdk.UpdateWorkspaceAutostartRequest": {
"type": "object",
"properties": {
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
index f08c130282126..f33bec806f70a 100644
--- a/coderd/apidoc/swagger.json
+++ b/coderd/apidoc/swagger.json
@@ -17,6 +17,22 @@
},
"basePath": "/api/v2",
"paths": {
+ "/": {
+ "get": {
+ "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 +112,52 @@
}
}
},
+ "/buildinfo": {
+ "get": {
+ "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": [
@@ -306,6 +368,22 @@
}
}
},
+ "/updatecheck": {
+ "get": {
+ "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": [
@@ -639,6 +717,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",
@@ -666,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": {
@@ -693,6 +780,19 @@
"type": "boolean"
}
},
+ "codersdk.BuildInfoResponse": {
+ "type": "object",
+ "properties": {
+ "external_url": {
+ "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": {
+ "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",
@@ -795,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"
}
}
@@ -960,6 +1060,23 @@
}
}
},
+ "codersdk.UpdateCheckResponse": {
+ "type": "object",
+ "properties": {
+ "current": {
+ "description": "Current indicates whether the server 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 release of Coder.",
+ "type": "string"
+ }
+ }
+ },
"codersdk.UpdateWorkspaceAutostartRequest": {
"type": "object",
"properties": {
diff --git a/coderd/apiroot.go b/coderd/apiroot.go
new file mode 100644
index 0000000000000..6974ca5133e24
--- /dev/null
+++ b/coderd/apiroot.go
@@ -0,0 +1,21 @@
+package coderd
+
+import (
+ "net/http"
+
+ "github.com/coder/coder/coderd/httpapi"
+ "github.com/coder/coder/codersdk"
+)
+
+// @Summary API root handler
+// @ID api-root-handler
+// @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..76497f8990e8a
--- /dev/null
+++ b/coderd/buildinfo.go
@@ -0,0 +1,22 @@
+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
+// @Produce json
+// @Tags General
+// @Success 200 {object} codersdk.BuildInfoResponse
+// @Router /buildinfo [get]
+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..ae3a0cbd99f93 100644
--- a/coderd/csp.go
+++ b/coderd/csp.go
@@ -15,6 +15,16 @@ type cspViolation struct {
}
// logReportCSPViolations will log all reported csp violations.
+//
+// @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]
func (api *API) logReportCSPViolations(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
var v cspViolation
diff --git a/coderd/updatecheck.go b/coderd/updatecheck.go
index a2c08ad879157..882a5e6f4b5a2 100644
--- a/coderd/updatecheck.go
+++ b/coderd/updatecheck.go
@@ -13,6 +13,12 @@ import (
"github.com/coder/coder/codersdk"
)
+// @Summary Update check
+// @ID update-check
+// @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/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 a8ba01e3716cb..19c7f21910ab3 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 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.
Version string `json:"version"`
diff --git a/codersdk/updatecheck.go b/codersdk/updatecheck.go
index 21da7ee309070..25f6bfc96e840 100644
--- a/codersdk/updatecheck.go
+++ b/codersdk/updatecheck.go
@@ -6,14 +6,11 @@ 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"`
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/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
new file mode 100644
index 0000000000000..8d5ef5dad967d
--- /dev/null
+++ b/docs/api/general.md
@@ -0,0 +1,138 @@
+# 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'
+```
+
+`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) |
+
+undefined
+
+## Build info
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/buildinfo \
+ -H 'Accept: application/json'
+```
+
+`GET /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) |
+
+undefined
+
+## 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 | |
+
+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'
+```
+
+`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) |
+
+undefined
diff --git a/docs/api/schemas.md b/docs/api/schemas.md
index d0eecaf5738ed..601a1fc7a396a 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 | | |
+
## codersdk.AuthorizationCheck
```json
@@ -27,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
@@ -49,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
@@ -105,6 +119,22 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in
| ---------------- | ------- | -------- | ------------ | ----------- |
| `[any property]` | boolean | false | | |
+## codersdk.BuildInfoResponse
+
+```json
+{
+ "external_url": "string",
+ "version": "string"
+}
+```
+
+### Properties
+
+| 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
```json
@@ -131,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
@@ -171,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
@@ -220,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
@@ -387,6 +417,24 @@ CreateParameterRequest is a structure used to create a new parameter value for a
| `p50` | integer | false | | |
| `p95` | integer | false | | |
+## codersdk.UpdateCheckResponse
+
+```json
+{
+ "current": true,
+ "url": "string",
+ "version": "string"
+}
+```
+
+### Properties
+
+| 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
```json
@@ -719,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
@@ -863,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
@@ -974,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/templates.md b/docs/api/templates.md
index 48301afd108f9..23a7260494db6 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 |
+| ------------------------------------ | --------------------------------- | -------- | ------------ | ------------------------------------------ |
+| `[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 | | |
+| `» build_time_stats` | `codersdk.TemplateBuildTimeStats` | false | | |
+| `»» [any property]` | `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..fcbfcda60d60e 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,31 +344,31 @@ 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
-| 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
@@ -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/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"
diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot
index c86d3570975e3..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);
}
}}
@@ -140,7 +155,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 1b00563cb37f4..47d81bd3d1863 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 }}
@@ -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 7d31119093c89..426d10227ccd3 100644
--- a/scripts/apidocgen/markdown-template/responses.def
+++ b/scripts/apidocgen/markdown-template/responses.def
@@ -24,6 +24,14 @@
}
return renderSingleResponseType(r);
}
+
+ function renderDisplayName(p) {
+ if (p.displayName == "*anonymous*") {
+ return "[array item]";
+ }
+ let displayName = p.displayName.replace("**additionalProperties**", "[any property]");
+ return displayName;
+ }
}}
{{ data.responses = data.utils.getResponses(data); }}
{{ data.responseSchemas = false; }}
@@ -77,7 +85,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||''}}|
{{~}}
{{~}}
{{?}}
@@ -87,7 +95,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)}}`|
{{~}}
{{?}}