Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit cfd02d9

Browse files
mtojekmtojek
authored
docs: api root, buildinfo, csp (#5493)
* 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
1 parent c505e8b commit cfd02d9

File tree

21 files changed

+682
-176
lines changed

21 files changed

+682
-176
lines changed

‎coderd/apidoc/docs.go‎

Lines changed: 137 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,26 @@ const docTemplate = `{
2525
"host": "{{.Host}}",
2626
"basePath": "{{.BasePath}}",
2727
"paths": {
28+
"/": {
29+
"get": {
30+
"produces": [
31+
"application/json"
32+
],
33+
"tags": [
34+
"General"
35+
],
36+
"summary": "API root handler",
37+
"operationId": "api-root-handler",
38+
"responses": {
39+
"200": {
40+
"description": "OK",
41+
"schema": {
42+
"$ref": "#/definitions/codersdk.Response"
43+
}
44+
}
45+
}
46+
}
47+
},
2848
"/applications/auth-redirect": {
2949
"get": {
3050
"security": [
@@ -116,6 +136,62 @@ const docTemplate = `{
116136
}
117137
}
118138
},
139+
"/buildinfo": {
140+
"get": {
141+
"produces": [
142+
"application/json"
143+
],
144+
"tags": [
145+
"General"
146+
],
147+
"summary": "Build info",
148+
"operationId": "build-info",
149+
"responses": {
150+
"200": {
151+
"description": "OK",
152+
"schema": {
153+
"$ref": "#/definitions/codersdk.BuildInfoResponse"
154+
}
155+
}
156+
}
157+
}
158+
},
159+
"/csp/reports": {
160+
"post": {
161+
"security": [
162+
{
163+
"CoderSessionToken": []
164+
}
165+
],
166+
"consumes": [
167+
"application/json"
168+
],
169+
"produces": [
170+
"text/plain"
171+
],
172+
"tags": [
173+
"General"
174+
],
175+
"summary": "Report CSP violations",
176+
"operationId": "report-csp-violations",
177+
"parameters": [
178+
{
179+
"description": "Violation report",
180+
"name": "request",
181+
"in": "body",
182+
"required": true,
183+
"schema": {
184+
"$ref": "#/definitions/coderd.cspViolation"
185+
}
186+
}
187+
],
188+
"responses": {
189+
"200": {
190+
"description": "OK"
191+
}
192+
}
193+
}
194+
},
119195
"/organizations/{organization-id}/templates/": {
120196
"post": {
121197
"security": [
@@ -352,6 +428,26 @@ const docTemplate = `{
352428
}
353429
}
354430
},
431+
"/updatecheck": {
432+
"get": {
433+
"produces": [
434+
"application/json"
435+
],
436+
"tags": [
437+
"General"
438+
],
439+
"summary": "Update check",
440+
"operationId": "update-check",
441+
"responses": {
442+
"200": {
443+
"description": "OK",
444+
"schema": {
445+
"$ref": "#/definitions/codersdk.UpdateCheckResponse"
446+
}
447+
}
448+
}
449+
}
450+
},
355451
"/users/{user}/workspace/{workspacename}": {
356452
"get": {
357453
"security": [
@@ -730,6 +826,15 @@ const docTemplate = `{
730826
}
731827
},
732828
"definitions": {
829+
"coderd.cspViolation": {
830+
"type": "object",
831+
"properties": {
832+
"csp-report": {
833+
"type": "object",
834+
"additionalProperties": true
835+
}
836+
}
837+
},
733838
"codersdk.AuthorizationCheck": {
734839
"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.",
735840
"type": "object",
@@ -762,7 +867,7 @@ const docTemplate = `{
762867
"type": "string"
763868
},
764869
"resource_id": {
765-
"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.",
870+
"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.",
766871
"type": "string"
767872
},
768873
"resource_type": {
@@ -789,6 +894,19 @@ const docTemplate = `{
789894
"type": "boolean"
790895
}
791896
},
897+
"codersdk.BuildInfoResponse": {
898+
"type": "object",
899+
"properties": {
900+
"external_url": {
901+
"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.",
902+
"type": "string"
903+
},
904+
"version": {
905+
"description": "Version returns the semantic version of the build.",
906+
"type": "string"
907+
}
908+
}
909+
},
792910
"codersdk.CreateParameterRequest": {
793911
"description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.",
794912
"type": "object",
@@ -899,7 +1017,7 @@ const docTemplate = `{
8991017
"type": "integer"
9001018
},
9011019
"url": {
902-
"description": "URL specifies the url to check for the app health.",
1020+
"description": "URL specifies the endpoint to check for the app health.",
9031021
"type": "string"
9041022
}
9051023
}
@@ -1066,6 +1184,23 @@ const docTemplate = `{
10661184
}
10671185
}
10681186
},
1187+
"codersdk.UpdateCheckResponse": {
1188+
"type": "object",
1189+
"properties": {
1190+
"current": {
1191+
"description": "Current indicates whether the server version is the same as the latest.",
1192+
"type": "boolean"
1193+
},
1194+
"url": {
1195+
"description": "URL to download the latest release of Coder.",
1196+
"type": "string"
1197+
},
1198+
"version": {
1199+
"description": "Version is the semantic version for the latest release of Coder.",
1200+
"type": "string"
1201+
}
1202+
}
1203+
},
10691204
"codersdk.UpdateWorkspaceAutostartRequest": {
10701205
"type": "object",
10711206
"properties": {

‎coderd/apidoc/swagger.json‎

Lines changed: 119 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,22 @@
1717
},
1818
"basePath": "/api/v2",
1919
"paths": {
20+
"/": {
21+
"get": {
22+
"produces": ["application/json"],
23+
"tags": ["General"],
24+
"summary": "API root handler",
25+
"operationId": "api-root-handler",
26+
"responses": {
27+
"200": {
28+
"description": "OK",
29+
"schema": {
30+
"$ref": "#/definitions/codersdk.Response"
31+
}
32+
}
33+
}
34+
}
35+
},
2036
"/applications/auth-redirect": {
2137
"get": {
2238
"security": [
@@ -96,6 +112,52 @@
96112
}
97113
}
98114
},
115+
"/buildinfo": {
116+
"get": {
117+
"produces": ["application/json"],
118+
"tags": ["General"],
119+
"summary": "Build info",
120+
"operationId": "build-info",
121+
"responses": {
122+
"200": {
123+
"description": "OK",
124+
"schema": {
125+
"$ref": "#/definitions/codersdk.BuildInfoResponse"
126+
}
127+
}
128+
}
129+
}
130+
},
131+
"/csp/reports": {
132+
"post": {
133+
"security": [
134+
{
135+
"CoderSessionToken": []
136+
}
137+
],
138+
"consumes": ["application/json"],
139+
"produces": ["text/plain"],
140+
"tags": ["General"],
141+
"summary": "Report CSP violations",
142+
"operationId": "report-csp-violations",
143+
"parameters": [
144+
{
145+
"description": "Violation report",
146+
"name": "request",
147+
"in": "body",
148+
"required": true,
149+
"schema": {
150+
"$ref": "#/definitions/coderd.cspViolation"
151+
}
152+
}
153+
],
154+
"responses": {
155+
"200": {
156+
"description": "OK"
157+
}
158+
}
159+
}
160+
},
99161
"/organizations/{organization-id}/templates/": {
100162
"post": {
101163
"security": [
@@ -306,6 +368,22 @@
306368
}
307369
}
308370
},
371+
"/updatecheck": {
372+
"get": {
373+
"produces": ["application/json"],
374+
"tags": ["General"],
375+
"summary": "Update check",
376+
"operationId": "update-check",
377+
"responses": {
378+
"200": {
379+
"description": "OK",
380+
"schema": {
381+
"$ref": "#/definitions/codersdk.UpdateCheckResponse"
382+
}
383+
}
384+
}
385+
}
386+
},
309387
"/users/{user}/workspace/{workspacename}": {
310388
"get": {
311389
"security": [
@@ -639,6 +717,15 @@
639717
}
640718
},
641719
"definitions": {
720+
"coderd.cspViolation": {
721+
"type": "object",
722+
"properties": {
723+
"csp-report": {
724+
"type": "object",
725+
"additionalProperties": true
726+
}
727+
}
728+
},
642729
"codersdk.AuthorizationCheck": {
643730
"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.",
644731
"type": "object",
@@ -666,7 +753,7 @@
666753
"type": "string"
667754
},
668755
"resource_id": {
669-
"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.",
756+
"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.",
670757
"type": "string"
671758
},
672759
"resource_type": {
@@ -693,6 +780,19 @@
693780
"type": "boolean"
694781
}
695782
},
783+
"codersdk.BuildInfoResponse": {
784+
"type": "object",
785+
"properties": {
786+
"external_url": {
787+
"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.",
788+
"type": "string"
789+
},
790+
"version": {
791+
"description": "Version returns the semantic version of the build.",
792+
"type": "string"
793+
}
794+
}
795+
},
696796
"codersdk.CreateParameterRequest": {
697797
"description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.",
698798
"type": "object",
@@ -795,7 +895,7 @@
795895
"type": "integer"
796896
},
797897
"url": {
798-
"description": "URL specifies the url to check for the app health.",
898+
"description": "URL specifies the endpoint to check for the app health.",
799899
"type": "string"
800900
}
801901
}
@@ -960,6 +1060,23 @@
9601060
}
9611061
}
9621062
},
1063+
"codersdk.UpdateCheckResponse": {
1064+
"type": "object",
1065+
"properties": {
1066+
"current": {
1067+
"description": "Current indicates whether the server version is the same as the latest.",
1068+
"type": "boolean"
1069+
},
1070+
"url": {
1071+
"description": "URL to download the latest release of Coder.",
1072+
"type": "string"
1073+
},
1074+
"version": {
1075+
"description": "Version is the semantic version for the latest release of Coder.",
1076+
"type": "string"
1077+
}
1078+
}
1079+
},
9631080
"codersdk.UpdateWorkspaceAutostartRequest": {
9641081
"type": "object",
9651082
"properties": {

‎coderd/apiroot.go‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
package coderd
2+
3+
import (
4+
"net/http"
5+
6+
"github.com/coder/coder/coderd/httpapi"
7+
"github.com/coder/coder/codersdk"
8+
)
9+
10+
// @Summary API root handler
11+
// @ID api-root-handler
12+
// @Produce json
13+
// @Tags General
14+
// @Success 200 {object} codersdk.Response
15+
// @Router / [get]
16+
func apiRoot(w http.ResponseWriter, r *http.Request) {
17+
httpapi.Write(r.Context(), w, http.StatusOK, codersdk.Response{
18+
//nolint:gocritic
19+
Message: "👋",
20+
})
21+
}

0 commit comments

Comments
 (0)