Skip to content

docs: audit, deploymentconfig, files, parameters #5506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 3, 2023
Merged

docs: audit, deploymentconfig, files, parameters #5506

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a3fbe72
docs: audit, deploymentconfig, files, parameters
mtojek Dec 22, 2022
c13dc1c
Fix: mark as binary
mtojek Jan 3, 2023
230d34a
Fix: show format in docs
mtojek Jan 3, 2023
a014423
Fix: use .swaggo
mtojek Jan 3, 2023
cbc7dcb
Merge branch 'main' into 3522-document-more-methods-3
mtojek Jan 3, 2023
b9a5f0e
Fix: swagger notice
mtojek Jan 3, 2023
ec782b2
Swagger notice
mtojek Jan 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Fix: show format in docs
  • Loading branch information
@mtojek
mtojek committed Jan 3, 2023
commit 230d34ad7cf95848bcbd3fdf1626bbaf08b772f8
9 changes: 6 additions & 3 deletions coderd/apidoc/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1983,7 +1983,8 @@ const docTemplate = `{
"type": "object",
"properties": {
"created_at": {
"type": "string"
"type": "string",
"format": "date-time"
},
"destination_scheme": {
"type": "string",
Expand Down Expand Up @@ -2020,7 +2021,8 @@ const docTemplate = `{
]
},
"updated_at": {
"type": "string"
"type": "string",
"format": "date-time"
}
}
},
Expand Down Expand Up @@ -2340,7 +2342,8 @@ const docTemplate = `{
"type": "object",
"properties": {
"hash": {
"type": "string"
"type": "string",
"format": "uuid"
}
}
},
Expand Down
9 changes: 6 additions & 3 deletions coderd/apidoc/swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1803,7 +1803,8 @@
"type": "object",
"properties": {
"created_at": {
"type": "string"
"type": "string",
"format": "date-time"
},
"destination_scheme": {
"type": "string",
Expand All @@ -1829,7 +1830,8 @@
"enum": ["none", "data"]
},
"updated_at": {
"type": "string"
"type": "string",
"format": "date-time"
}
}
},
Expand Down Expand Up @@ -2147,7 +2149,8 @@
"type": "object",
"properties": {
"hash": {
"type": "string"
"type": "string",
"format": "uuid"
}
}
},
Expand Down
2 changes: 1 addition & 1 deletion codersdk/files.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ const (

// UploadResponse contains the hash to reference the uploaded file.
type UploadResponse struct {
ID uuid.UUID `json:"hash"`
ID uuid.UUID `json:"hash" format:"uuid"`
}

// Upload uploads an arbitrary file with the content type provided.
Expand Down
16 changes: 8 additions & 8 deletions codersdk/parameters.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ const (
type ComputedParameter struct {
Parameter
SourceValue string `json:"source_value"`
SchemaID uuid.UUID `json:"schema_id"`
SchemaID uuid.UUID `json:"schema_id" format:"uuid"`
DefaultSourceValue bool `json:"default_source_value"`
}

Expand All @@ -58,20 +58,20 @@ type Parameter struct {
Name string `json:"name" table:"name"`
SourceScheme ParameterSourceScheme `json:"source_scheme" table:"source scheme" validate:"ne=none" enums:"none,data"`
DestinationScheme ParameterDestinationScheme `json:"destination_scheme" table:"destination scheme" validate:"ne=none" enums:"none,environment_variable,provisioner_variable"`
CreatedAt time.Time `json:"created_at" table:"created at"`
UpdatedAt time.Time `json:"updated_at" table:"updated at"`
CreatedAt time.Time `json:"created_at" table:"created at" format:"date-time"`
UpdatedAt time.Time `json:"updated_at" table:"updated at" format:"date-time"`
}

type ParameterSchema struct {
ID uuid.UUID `json:"id"`
CreatedAt time.Time `json:"created_at"`
JobID uuid.UUID `json:"job_id"`
ID uuid.UUID `json:"id" format:"uuid"`
CreatedAt time.Time `json:"created_at" format:"date-time"`
JobID uuid.UUID `json:"job_id" format:"uuid"`
Name string `json:"name"`
Description string `json:"description"`
DefaultSourceScheme ParameterSourceScheme `json:"default_source_scheme"`
DefaultSourceScheme ParameterSourceScheme `json:"default_source_scheme" enums:"none,data"`
DefaultSourceValue string `json:"default_source_value"`
AllowOverrideSource bool `json:"allow_override_source"`
DefaultDestinationScheme ParameterDestinationScheme `json:"default_destination_scheme"`
DefaultDestinationScheme ParameterDestinationScheme `json:"default_destination_scheme" enums:"none,environment_variable,provisioner_variable"`
AllowOverrideDestination bool `json:"allow_override_destination"`
DefaultRefresh string `json:"default_refresh"`
RedisplayValue bool `json:"redisplay_value"`
Expand Down
2 changes: 1 addition & 1 deletion docs/api/files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ file: string

```json
{
"hash": "string"
"hash": "19686d84-b10d-4f90-b18e-84fd3fa038fd"
}
```

Expand Down
30 changes: 15 additions & 15 deletions docs/api/parameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,14 +37,14 @@ curl -X GET http://coder-server:8080/api/v2/parameters/{scope}/{id} \
```json
[
{
"created_at": "string",
"created_at": "2019-08-24T14:15:22Z",
"destination_scheme": "none",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"scope": "template",
"scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
"source_scheme": "none",
"updated_at": "string"
"updated_at": "2019-08-24T14:15:22Z"
}
]
```
Expand All @@ -59,17 +59,17 @@ curl -X GET http://coder-server:8080/api/v2/parameters/{scope}/{id} \

Status Code **200**

| Name | Type | Required | Restrictions | Description |
| ---------------------- | ------ | -------- | ------------ | ------------------------------------------------- |
| `[array item]` | array | false | | [Parameter represents a set value for the scope.] |
| `» created_at` | string | false | | |
| `» destination_scheme` | string | false | | |
| `» id` | string | false | | |
| `» name` | string | false | | |
| `» scope` | string | false | | |
| `» scope_id` | string | false | | |
| `» source_scheme` | string | false | | |
| `» updated_at` | string | false | | |
| Name | Type | Required | Restrictions | Description |
| ---------------------- | ----------------- | -------- | ------------ | ------------------------------------------------- |
| `[array item]` | array | false | | [Parameter represents a set value for the scope.] |
| `» created_at` | string(date-time) | false | | |
| `» destination_scheme` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» scope` | string | false | | |
| `» scope_id` | string(uuid) | false | | |
| `» source_scheme` | string | false | | |
| `» updated_at` | string(date-time) | false | | |

#### Enumerated Values

Expand Down Expand Up @@ -134,14 +134,14 @@ curl -X POST http://coder-server:8080/api/v2/parameters/{scope}/{id} \

```json
{
"created_at": "string",
"created_at": "2019-08-24T14:15:22Z",
"destination_scheme": "none",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"scope": "template",
"scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
"source_scheme": "none",
"updated_at": "string"
"updated_at": "2019-08-24T14:15:22Z"
}
```

Expand Down
6 changes: 3 additions & 3 deletions docs/api/schemas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2092,14 +2092,14 @@ CreateParameterRequest is a structure used to create a new parameter value for a

```json
{
"created_at": "string",
"created_at": "2019-08-24T14:15:22Z",
"destination_scheme": "none",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"scope": "template",
"scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
"source_scheme": "none",
"updated_at": "string"
"updated_at": "2019-08-24T14:15:22Z"
}
```

Expand Down Expand Up @@ -2760,7 +2760,7 @@ Parameter represents a set value for the scope.

```json
{
"hash": "string"
"hash": "19686d84-b10d-4f90-b18e-84fd3fa038fd"
}
```

Expand Down
10 changes: 5 additions & 5 deletions docs/api/templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,18 +165,18 @@ Status Code **200**
| `»» [any property]` | `codersdk.TransitionStats` | false | | |
| `»»» p50` | integer | false | | |
| `»»» p95` | integer | false | | |
| `» created_at` | string | false | | |
| `» created_by_id` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by_id` | string(uuid) | false | | |
| `» created_by_name` | string | false | | |
| `» default_ttl_ms` | integer | false | | |
| `» description` | string | false | | |
| `» display_name` | string | false | | |
| `» icon` | string | false | | |
| `» id` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» organization_id` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» provisioner` | string | false | | |
| `» updated_at` | string | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» workspace_owner_count` | integer | false | | |

To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
Expand Down
14 changes: 13 additions & 1 deletion scripts/apidocgen/markdown-template/responses.def
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,18 @@
let displayName = p.displayName.replace("**additionalProperties**", "[any property]");
return displayName;
}

function renderResponsePropertyType(p) {
if (p.$ref) {
return '`' + p.$ref + '`';
}

if (p.type == 'array') {
return p.type;
}

return p.safeType;
}
}}
{{ data.responses = data.utils.getResponses(data); }}
{{ data.responseSchemas = false; }}
Expand Down Expand Up @@ -85,7 +97,7 @@ Status Code **{{=response.status}}**
{{?}}
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
{{~}}
{{~}}
{{?}}
Expand Down