synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-08 11:39:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: api root, buildinfo, csp (#5493)

Browse Source 
* docs: Applications

* WIP

* WIP

* WIP

* Fix: consume

* Fix: @Description

* Fix

* docs: apiroot, buildinfo, csp

* Fix: buildinfo

* docs: updatecheck

* docs: apiroot

* Fix: s/none//g

* Fix: godoc nice

* Fix: description

* Fix: It

* Fix: code sample trim empty line

* More fixes

* Fix: br

* Merge

* Fix: no-security on updatecheck

* Fix: code tags

* Fix: enumerated values in code tags

* Rephrased

* Address PR comments

* Fix: URL, id

* Fix: array items

* Fix: any property

* Fix: array item singular
This commit is contained in:
Marcin Tojek
2022-12-22 15:53:14 +01:00
committed by GitHub
parent c505e8b207
commit cfd02d959c
21 changed files with 682 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
coderd/apidoc/docs.go
View File

@ -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": {

121
coderd/apidoc/swagger.json
View File

@ -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": {

21
coderd/apiroot.go Normal file
View File

@ -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: "👋",
})
}

22
coderd/buildinfo.go Normal file
View File

@ -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(),
})
}

20
coderd/coderd.go
View File

@ -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)

10
coderd/csp.go
View File

@ -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

6
coderd/updatecheck.go
View File

@ -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()