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

Skip to content

Commit a3fbe72

Browse files
mtojekmtojek
committed
docs: audit, deploymentconfig, files, parameters
1 parent cfd02d9 commit a3fbe72

21 files changed

+6334
-341
lines changed

‎coderd/apidoc/docs.go

Lines changed: 1329 additions & 162 deletions
Large diffs are not rendered by default.

‎coderd/apidoc/swagger.json

Lines changed: 1106 additions & 13 deletions
Large diffs are not rendered by default.

‎coderd/audit.go

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,17 @@ import (
2424
"github.com/coder/coder/codersdk"
2525
)
2626

27+
// @Summary Get audit logs
28+
// @ID get-audit-logs
29+
// @Security CoderSessionToken
30+
// @Produce json
31+
// @Tags Audit
32+
// @Param q query string true "Search query"
33+
// @Param after_id query string false "After ID" format(uuid)
34+
// @Param limit query int false "Page limit"
35+
// @Param offset query int false "Page offset"
36+
// @Success 200 {object} codersdk.AuditLogResponse
37+
// @Router /audit [get]
2738
func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
2839
ctx := r.Context()
2940
if !api.Authorize(r, rbac.ActionRead, rbac.ResourceAuditLog) {
@@ -77,6 +88,14 @@ func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
7788
})
7889
}
7990

91+
// @Summary Generate fake audit log
92+
// @ID generate-fake-audit-logs
93+
// @Security CoderSessionToken
94+
// @Accept json
95+
// @Tags Audit
96+
// @Param request body codersdk.CreateTestAuditLogRequest true "Audit log request"
97+
// @Success 204
98+
// @Router /audit/testgenerate [post]
8099
func (api *API) generateFakeAuditLog(rw http.ResponseWriter, r *http.Request) {
81100
ctx := r.Context()
82101
if !api.Authorize(r, rbac.ActionCreate, rbac.ResourceAuditLog) {

‎coderd/deploymentconfig.go

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ import (
77
"github.com/coder/coder/coderd/rbac"
88
)
99

10+
// @Summary Get deployment config
11+
// @ID get-deployment-config
12+
// @Security CoderSessionToken
13+
// @Produce json
14+
// @Tags General
15+
// @Success 200 {object} codersdk.DeploymentConfig
16+
// @Router /config/deployment [get]
1017
func (api *API) deploymentConfig(rw http.ResponseWriter, r *http.Request) {
1118
if !api.Authorize(r, rbac.ActionRead, rbac.ResourceDeploymentConfig) {
1219
httpapi.Forbidden(rw)

‎coderd/files.go

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,17 @@ const (
2323
tarMimeType = "application/x-tar"
2424
)
2525

26+
// @Summary Upload file
27+
// @Description Notice: Swagger 2.0 doesn't support file upload with a `content-type` different than `application/x-www-form-urlencoded`.
28+
// @ID update-file
29+
// @Security CoderSessionToken
30+
// @Produce json
31+
// @Accept application/x-tar
32+
// @Tags Files
33+
// @Param Content-Type header string true "Content-Type must be `application/x-tar`" default(application/x-tar)
34+
// @Param file formData file true "File to be uploaded"
35+
// @Success 201 {object} codersdk.UploadResponse
36+
// @Router /files [post]
2637
func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
2738
ctx := r.Context()
2839
apiKey := httpmw.APIKey(r)
@@ -88,6 +99,13 @@ func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
8899
})
89100
}
90101

102+
// @Summary Get file by ID
103+
// @ID get-file-by-id
104+
// @Security CoderSessionToken
105+
// @Tags Files
106+
// @Param fileID path string true "File ID" format(uuid)
107+
// @Success 200
108+
// @Router /files/{fileID} [get]
91109
func (api *API) fileByID(rw http.ResponseWriter, r *http.Request) {
92110
ctx := r.Context()
93111

‎coderd/parameters.go

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,17 @@ import (
1818
"github.com/coder/coder/codersdk"
1919
)
2020

21+
// @Summary Create parameter
22+
// @ID create-parameter
23+
// @Security CoderSessionToken
24+
// @Accept json
25+
// @Produce json
26+
// @Tags Parameters
27+
// @Param request body codersdk.CreateParameterRequest true "Parameter request"
28+
// @Param scope path string true "Scope" Enums(template,workspace,import_job)
29+
// @Param id path string true "ID" format(uuid)
30+
// @Success 201 {object} codersdk.Parameter
31+
// @Router /parameters/{scope}/{id} [post]
2132
func (api *API) postParameter(rw http.ResponseWriter, r *http.Request) {
2233
ctx := r.Context()
2334
scope, scopeID, valid := readScopeAndID(ctx, rw, r)
@@ -78,6 +89,15 @@ func (api *API) postParameter(rw http.ResponseWriter, r *http.Request) {
7889
httpapi.Write(ctx, rw, http.StatusCreated, convertParameterValue(parameterValue))
7990
}
8091

92+
// @Summary Get parameters
93+
// @ID get-parameters
94+
// @Security CoderSessionToken
95+
// @Produce json
96+
// @Tags Parameters
97+
// @Param scope path string true "Scope" Enums(template,workspace,import_job)
98+
// @Param id path string true "ID" format(uuid)
99+
// @Success 200 {array} codersdk.Parameter
100+
// @Router /parameters/{scope}/{id} [get]
81101
func (api *API) parameters(rw http.ResponseWriter, r *http.Request) {
82102
ctx := r.Context()
83103
scope, scopeID, valid := readScopeAndID(ctx, rw, r)
@@ -116,6 +136,16 @@ func (api *API) parameters(rw http.ResponseWriter, r *http.Request) {
116136
httpapi.Write(ctx, rw, http.StatusOK, apiParameterValues)
117137
}
118138

139+
// @Summary Delete parameter
140+
// @ID delete-parameter
141+
// @Security CoderSessionToken
142+
// @Produce json
143+
// @Tags Parameters
144+
// @Param scope path string true "Scope" Enums(template,workspace,import_job)
145+
// @Param id path string true "ID" format(uuid)
146+
// @Param name path string true "Name"
147+
// @Success 200 {object} codersdk.Response
148+
// @Router /parameters/{scope}/{id}/{name} [delete]
119149
func (api *API) deleteParameter(rw http.ResponseWriter, r *http.Request) {
120150
ctx := r.Context()
121151
scope, scopeID, valid := readScopeAndID(ctx, rw, r)

‎coderd/templates.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -478,7 +478,7 @@ func (api *API) templateByOrganizationAndName(rw http.ResponseWriter, r *http.Re
478478
// @Tags Templates
479479
// @Param id path string true "Template ID" format(uuid)
480480
// @Success 200 {object} codersdk.Template
481-
// @Router /templates/{id} [get]
481+
// @Router /templates/{id} [patch]
482482
func (api *API) patchTemplateMeta(rw http.ResponseWriter, r *http.Request) {
483483
var (
484484
ctx = r.Context()

‎codersdk/audit.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,8 @@ type AuditLogResponse struct {
121121
}
122122

123123
type CreateTestAuditLogRequest struct {
124-
Action AuditAction `json:"action,omitempty"`
125-
ResourceType ResourceType `json:"resource_type,omitempty"`
124+
Action AuditAction `json:"action,omitempty" enums:"create,write,delete,start,stop"`
125+
ResourceType ResourceType `json:"resource_type,omitempty" enums:"organization,template,template_version,user,workspace,workspace_build,git_ssh_key,api_key,group"`
126126
ResourceID uuid.UUID `json:"resource_id,omitempty"`
127127
Time time.Time `json:"time,omitempty"`
128128
}

‎codersdk/parameters.go

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,15 @@ type ComputedParameter struct {
4949
}
5050

5151
// Parameter represents a set value for the scope.
52+
//
53+
// @Description Parameter represents a set value for the scope.
5254
type Parameter struct {
53-
ID uuid.UUID `json:"id" table:"id"`
54-
Scope ParameterScope `json:"scope" table:"scope"`
55-
ScopeID uuid.UUID `json:"scope_id" table:"scope id"`
55+
ID uuid.UUID `json:"id" table:"id" format:"uuid"`
56+
Scope ParameterScope `json:"scope" table:"scope" enums:"template,workspace,import_job"`
57+
ScopeID uuid.UUID `json:"scope_id" table:"scope id" format:"uuid"`
5658
Name string `json:"name" table:"name"`
57-
SourceScheme ParameterSourceScheme `json:"source_scheme" table:"source scheme" validate:"ne=none"`
58-
DestinationScheme ParameterDestinationScheme `json:"destination_scheme" table:"destination scheme" validate:"ne=none"`
59+
SourceScheme ParameterSourceScheme `json:"source_scheme" table:"source scheme" validate:"ne=none" enums:"none,data"`
60+
DestinationScheme ParameterDestinationScheme `json:"destination_scheme" table:"destination scheme" validate:"ne=none" enums:"none,environment_variable,provisioner_variable"`
5961
CreatedAt time.Time `json:"created_at" table:"created at"`
6062
UpdatedAt time.Time `json:"updated_at" table:"updated at"`
6163
}
@@ -96,8 +98,8 @@ type CreateParameterRequest struct {
9698

9799
Name string `json:"name" validate:"required"`
98100
SourceValue string `json:"source_value" validate:"required"`
99-
SourceScheme ParameterSourceScheme `json:"source_scheme" validate:"oneof=data,required"`
100-
DestinationScheme ParameterDestinationScheme `json:"destination_scheme" validate:"oneof=environment_variable provisioner_variable,required"`
101+
SourceScheme ParameterSourceScheme `json:"source_scheme" validate:"oneof=data,required" enums:"none,data"`
102+
DestinationScheme ParameterDestinationScheme `json:"destination_scheme" validate:"oneof=environment_variable provisioner_variable,required" enums:"none,environment_variable,provisioner_variable"`
101103
}
102104

103105
func (c *Client) CreateParameter(ctx context.Context, scope ParameterScope, id uuid.UUID, req CreateParameterRequest) (Parameter, error) {

‎codersdk/workspacebuilds.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ type WorkspaceBuild struct {
6767
Job ProvisionerJob `json:"job"`
6868
Reason BuildReason `db:"reason" json:"reason"`
6969
Resources []WorkspaceResource `json:"resources"`
70-
Deadline NullTime `json:"deadline,omitempty"`
70+
Deadline NullTime `json:"deadline,omitempty" swaggertype:"string" format:"date-time"`
7171
Status WorkspaceStatus `json:"status" enums:"pending,starting,running,stopping,stopped,failed,canceling,canceled,deleting,deleted"`
7272
DailyCost int32 `json:"daily_cost"`
7373
}

‎docs/api/audit.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Audit
2+
3+
> This page is incomplete, stay tuned.
4+
5+
## Get audit logs
6+
7+
### Code samples
8+
9+
```shell
10+
# Example request using curl
11+
curl -X GET http://coder-server:8080/api/v2/audit?q=string \
12+
-H 'Accept: application/json' \
13+
-H 'Coder-Session-Token: API_KEY'
14+
```
15+
16+
`GET /audit`
17+
18+
### Parameters
19+
20+
| Name | In | Type | Required | Description |
21+
| ---------- | ----- | ------------ | -------- | ------------ |
22+
| `q` | query | string | true | Search query |
23+
| `after_id` | query | string(uuid) | false | After ID |
24+
| `limit` | query | integer | false | Page limit |
25+
| `offset` | query | integer | false | Page offset |
26+
27+
### Example responses
28+
29+
> 200 Response
30+
31+
```json
32+
{
33+
"audit_logs": [
34+
{
35+
"action": "string",
36+
"additional_fields": [0],
37+
"description": "string",
38+
"diff": {
39+
"property1": {
40+
"new": null,
41+
"old": null,
42+
"secret": true
43+
},
44+
"property2": {
45+
"new": null,
46+
"old": null,
47+
"secret": true
48+
}
49+
},
50+
"id": "string",
51+
"ip": {},
52+
"is_deleted": true,
53+
"organization_id": "string",
54+
"request_id": "string",
55+
"resource_icon": "string",
56+
"resource_id": "string",
57+
"resource_link": "string",
58+
"resource_target": "string",
59+
"resource_type": "string",
60+
"status_code": 0,
61+
"time": "string",
62+
"user": {
63+
"avatar_url": "string",
64+
"created_at": "string",
65+
"email": "string",
66+
"id": "string",
67+
"last_seen_at": "string",
68+
"organization_ids": ["string"],
69+
"roles": [
70+
{
71+
"display_name": "string",
72+
"name": "string"
73+
}
74+
],
75+
"status": "string",
76+
"username": "string"
77+
},
78+
"user_agent": "string"
79+
}
80+
],
81+
"count": 0
82+
}
83+
```
84+
85+
### Responses
86+
87+
| Status | Meaning | Description | Schema |
88+
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
89+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AuditLogResponse](schemas.md#codersdkauditlogresponse) |
90+
91+
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
92+
93+
## Generate fake audit log
94+
95+
### Code samples
96+
97+
```shell
98+
# Example request using curl
99+
curl -X POST http://coder-server:8080/api/v2/audit/testgenerate \
100+
-H 'Content-Type: application/json' \
101+
-H 'Coder-Session-Token: API_KEY'
102+
```
103+
104+
`POST /audit/testgenerate`
105+
106+
> Body parameter
107+
108+
```json
109+
{
110+
"action": "create",
111+
"resource_id": "string",
112+
"resource_type": "organization",
113+
"time": "string"
114+
}
115+
```
116+
117+
### Parameters
118+
119+
| Name | In | Type | Required | Description |
120+
| ------ | ---- | ---------------------------------------------------------------------------------- | -------- | ----------------- |
121+
| `body` | body | [codersdk.CreateTestAuditLogRequest](schemas.md#codersdkcreatetestauditlogrequest) | true | Audit log request |
122+
123+
### Responses
124+
125+
| Status | Meaning | Description | Schema |
126+
| ------ | --------------------------------------------------------------- | ----------- | ------ |
127+
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
128+
129+
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.

‎docs/api/files.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Files
2+
3+
> This page is incomplete, stay tuned.
4+
5+
## Upload file
6+
7+
### Code samples
8+
9+
```shell
10+
# Example request using curl
11+
curl -X POST http://coder-server:8080/api/v2/files \
12+
-H 'Accept: application/json' \
13+
-H 'Content-Type: application/x-tar' \
14+
-H 'Coder-Session-Token: API_KEY'
15+
```
16+
17+
`POST /files`
18+
19+
Notice: Swagger 2.0 doesn't support file upload with a `content-type` different than `application/x-www-form-urlencoded`.
20+
21+
> Body parameter
22+
23+
```yaml
24+
file: string
25+
```
26+
27+
### Parameters
28+
29+
| Name | In | Type | Required | Description |
30+
| -------------- | ------ | -------------- | -------- | ---------------------------------------- |
31+
| `Content-Type` | header | string | true | Content-Type must be `application/x-tar` |
32+
| `body` | body | object | true | |
33+
| `» file` | body | string(binary) | true | File to be uploaded |
34+
35+
### Example responses
36+
37+
> 201 Response
38+
39+
```json
40+
{
41+
"hash": "string"
42+
}
43+
```
44+
45+
### Responses
46+
47+
| Status | Meaning | Description | Schema |
48+
| ------ | ------------------------------------------------------------ | ----------- | ------------------------------------------------------------ |
49+
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.UploadResponse](schemas.md#codersdkuploadresponse) |
50+
51+
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
52+
53+
## Get file by ID
54+
55+
### Code samples
56+
57+
```shell
58+
# Example request using curl
59+
curl -X GET http://coder-server:8080/api/v2/files/{fileID} \
60+
-H 'Coder-Session-Token: API_KEY'
61+
```
62+
63+
`GET /files/{fileID}`
64+
65+
### Parameters
66+
67+
| Name | In | Type | Required | Description |
68+
| -------- | ---- | ------------ | -------- | ----------- |
69+
| `fileID` | path | string(uuid) | true | File ID |
70+
71+
### Responses
72+
73+
| Status | Meaning | Description | Schema |
74+
| ------ | ------------------------------------------------------- | ----------- | ------ |
75+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
76+
77+
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.

0 commit comments

Comments
 (0)