Members

coder · mtojek · Jan 11, 2023 · Dec 22, 2022 · Jan 2, 2023 · Jan 2, 2023
commit 7aa0f65857611cbc64c5491908529c21c3aa9a18
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/members.go b/coderd/members.go
@@ -16,6 +16,17 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Assign role to organization member
+// @ID assign-role-to-organization-member
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Members
+// @Param request body codersdk.UpdateRoles true "Update roles request"
+// @Param organization path string true "Organization ID"
+// @Param user path string true "Username, UUID, or me"
+// @Success 200 {object} codersdk.OrganizationMember
+// @Router /organizations/{organization}/members/{user}/roles [put]
 func (api *API) putMemberRoles(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx          = r.Context()

diff --git a/coderd/organizations.go b/coderd/organizations.go
@@ -21,9 +21,9 @@ import (
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Organizations
-// @Param id path string true "Organization ID" format(uuid)
+// @Param organization path string true "Organization ID" format(uuid)
 // @Success 200 {object} codersdk.Organization
-// @Router /organizations/{id} [get]
+// @Router /organizations/{organization} [get]
 func (api *API) organization(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)

diff --git a/coderd/roles.go b/coderd/roles.go
@@ -23,6 +23,15 @@ func (api *API) assignableSiteRoles(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, assignableRoles(actorRoles.Roles, roles))
 }
 
+// @Summary Get member roles by organization
+// @ID get-member-roles-by-organization
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Members
+// @Param organization path string true "Organization ID" format(uuid)
+// @Success 200 {array} codersdk.AssignableRoles
+// @Router /organizations/{organization}/members/roles [get]
+//
 // assignableSiteRoles returns all site wide roles that can be assigned.
 func (api *API) assignableOrgRoles(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()

diff --git a/coderd/templates.go b/coderd/templates.go
@@ -149,9 +149,9 @@ func (api *API) deleteTemplate(rw http.ResponseWriter, r *http.Request) {
 // @Produce json
 // @Tags Templates
 // @Param request body codersdk.CreateTemplateRequest true "Request body"
-// @Param organization-id path string true "Organization ID"
+// @Param organization path string true "Organization ID"
 // @Success 200 {object} codersdk.Template
-// @Router /organizations/{organization-id}/templates/ [post]
+// @Router /organizations/{organization}/templates [post]
 // Returns a single template.
 // Create a new template in an organization.
 func (api *API) postTemplateByOrganization(rw http.ResponseWriter, r *http.Request) {
@@ -347,7 +347,7 @@ func (api *API) postTemplateByOrganization(rw http.ResponseWriter, r *http.Reque
 // @Produce json
 // @Tags Templates
 // @Param organization path string true "Organization ID" format(uuid)
-// @Success 200 {object} []codersdk.Template
+// @Success 200 {array} codersdk.Template
 // @Router /organizations/{organization}/templates [get]
 func (api *API) templatesByOrganization(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
@@ -413,9 +413,9 @@ func (api *API) templatesByOrganization(rw http.ResponseWriter, r *http.Request)
 // @Produce json
 // @Tags Templates
 // @Param organization path string true "Organization ID" format(uuid)
-// @Param template-name path string true "Template name"
+// @Param templatename path string true "Template name"
 // @Success 200 {object} codersdk.Template
-// @Router /organizations/{organization}/templates/{template-name} [get]
+// @Router /organizations/{organization}/templates/{templatename} [get]
 func (api *API) templateByOrganizationAndName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)
@@ -625,6 +625,14 @@ func (api *API) templateDAUs(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, resp)
 }
 
+// @Summary Get template examples by organization
+// @ID get-template-examples-by-organization
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param organization path string true "Organization ID" format(uuid)
+// @Success 200 {array} codersdk.TemplateExample
+// @Router /organizations/{organization}/templates/examples [get]
 func (api *API) templateExamples(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx          = r.Context()

diff --git a/coderd/templateversions.go b/coderd/templateversions.go
@@ -646,9 +646,9 @@ func (api *API) templateVersionsByTemplate(rw http.ResponseWriter, r *http.Reque
 // @Produce json
 // @Tags Templates
 // @Param id path string true "Template ID" format(uuid)
-// @Param name path string true "Template name"
+// @Param templateversionname path string true "Template version name"
 // @Success 200 {array} codersdk.TemplateVersion
-// @Router /templates/{id}/versions/{name} [get]
+// @Router /templates/{id}/versions/{templateversionname} [get]
 func (api *API) templateVersionByName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	template := httpmw.TemplateParam(r)
@@ -699,6 +699,15 @@ func (api *API) templateVersionByName(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertTemplateVersion(templateVersion, convertProvisionerJob(job), user))
 }
 
+// @Summary Get template version by organization and name
+// @ID get-template-version-by-organization-and-name
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param organization path string true "Organization ID" format(uuid)
+// @Param templateversionname path string true "Template version name"
+// @Success 200 {object} codersdk.TemplateVersion
+// @Router /organizations/{organization}/templateversions/{templateversionname} [get]
 func (api *API) templateVersionByOrganizationAndName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)
@@ -741,6 +750,15 @@ func (api *API) templateVersionByOrganizationAndName(rw http.ResponseWriter, r *
 	httpapi.Write(ctx, rw, http.StatusOK, convertTemplateVersion(templateVersion, convertProvisionerJob(job), user))
 }
 
+// @Summary Get previous template version by organization and name
+// @ID get-previous-template-version-by-organization-and-name
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param organization path string true "Organization ID" format(uuid)
+// @Param templateversionname path string true "Template version name"
+// @Success 200 {object} codersdk.TemplateVersion
+// @Router /organizations/{organization}/templateversions/{templateversionname} [get]
 func (api *API) previousTemplateVersionByOrganizationAndName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)
@@ -890,7 +908,18 @@ func (api *API) patchActiveTemplateVersion(rw http.ResponseWriter, r *http.Reque
 	})
 }
 
-// Creates a new version of a template. An import job is queued to parse the storage method provided.
+// @Summary Create template version by organization
+// @ID create-template-version-by-organization
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Templates
+// @Param organization path string true "Organization ID" format(uuid)
+// @Param request body codersdk.CreateTemplateVersionDryRunRequest true "Create template version request"
+// @Success 201 {object} codersdk.TemplateVersion
+// @Router /organizations/{organization}/templateversions [post]
+//
+// postTemplateVersionsByOrganization creates a new version of a template. An import job is queued to parse the storage method provided.
 func (api *API) postTemplateVersionsByOrganization(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()

diff --git a/coderd/workspaces.go b/coderd/workspaces.go
@@ -266,15 +266,16 @@ func (api *API) workspaceByOwnerAndName(rw http.ResponseWriter, r *http.Request)
 	))
 }
 
-// @Summary Create workspace by organization
-// @ID create-workspace-by-organization
+// @Summary Create user workspace by organization
+// @ID create-user-workspace-by-organization
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Workspaces
 // @Param organization path string true "Organization ID" format(uuid)
-// @Param user path string true "Username"
+// @Param user path string true "Username, UUID, or me"
 // @Success 200 {object} codersdk.Workspace
 // @Router /organizations/{organization}/members/{user}/workspaces [post]
+//
 // Create a new workspace for the currently authenticated user.
 func (api *API) postWorkspacesByOrganization(rw http.ResponseWriter, r *http.Request) {
 	var (

diff --git a/codersdk/organizationmember.go b/codersdk/organizationmember.go
@@ -7,9 +7,9 @@ import (
 )
 
 type OrganizationMember struct {
-	UserID         uuid.UUID `db:"user_id" json:"user_id"`
-	OrganizationID uuid.UUID `db:"organization_id" json:"organization_id"`
-	CreatedAt      time.Time `db:"created_at" json:"created_at"`
-	UpdatedAt      time.Time `db:"updated_at" json:"updated_at"`
+	UserID         uuid.UUID `db:"user_id" json:"user_id" format:"uuid"`
+	OrganizationID uuid.UUID `db:"organization_id" json:"organization_id" format:"uuid"`
+	CreatedAt      time.Time `db:"created_at" json:"created_at" format:"date-time"`
+	UpdatedAt      time.Time `db:"updated_at" json:"updated_at" format:"date-time"`
 	Roles          []Role    `db:"roles" json:"roles"`
 }
diff --git a/docs/api/members.md b/docs/api/members.md
@@ -0,0 +1,112 @@
+# Members
+
+> This page is incomplete, stay tuned.
+
+## Get member roles by organization
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/members/roles \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`GET /organizations/{organization}/members/roles`
+
+### Parameters
+
+| Name           | In   | Type         | Required | Description     |
+| -------------- | ---- | ------------ | -------- | --------------- |
+| `organization` | path | string(uuid) | true     | Organization ID |
+
+### Example responses
+
+> 200 Response
+
+```json
+[
+  {
+    "assignable": true,
+    "display_name": "string",
+    "name": "string"
+  }
+]
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                                  |
+| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | array of [codersdk.AssignableRoles](schemas.md#codersdkassignableroles) |
+
+<h3 id="get-member-roles-by-organization-responseschema">Response Schema</h3>
+
+Status Code **200**
+
+| Name             | Type    | Required | Restrictions | Description |
+| ---------------- | ------- | -------- | ------------ | ----------- |
+| `[array item]`   | array   | false    |              |             |
+| `» assignable`   | boolean | false    |              |             |
+| `» display_name` | string  | false    |              |             |
+| `» name`         | string  | false    |              |             |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
+
+## Assign role to organization member
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X PUT http://coder-server:8080/api/v2/organizations/{organization}/members/{user}/roles \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`PUT /organizations/{organization}/members/{user}/roles`
+
+> Body parameter
+
+```json
+{
+  "roles": ["string"]
+}
+```
+
+### Parameters
+
+| Name           | In   | Type                                                   | Required | Description           |
+| -------------- | ---- | ------------------------------------------------------ | -------- | --------------------- |
+| `organization` | path | string                                                 | true     | Organization ID       |
+| `user`         | path | string                                                 | true     | Username, UUID, or me |
+| `body`         | body | [codersdk.UpdateRoles](schemas.md#codersdkupdateroles) | true     | Update roles request  |
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "created_at": "2019-08-24T14:15:22Z",
+  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
+  "roles": [
+    {
+      "display_name": "string",
+      "name": "string"
+    }
+  ],
+  "updated_at": "2019-08-24T14:15:22Z",
+  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                               |
+| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.OrganizationMember](schemas.md#codersdkorganizationmember) |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
diff --git a/docs/api/organizations.md b/docs/api/organizations.md
@@ -57,18 +57,18 @@ To perform this operation, you must be authenticated by means of one of the foll
 
 ```shell
 # Example request using curl
-curl -X GET http://coder-server:8080/api/v2/organizations/{id} \
+curl -X GET http://coder-server:8080/api/v2/organizations/{organization} \
   -H 'Accept: application/json' \
   -H 'Coder-Session-Token: API_KEY'
 ```
 
-`GET /organizations/{id}`
+`GET /organizations/{organization}`
 
 ### Parameters
 
-| Name | In   | Type         | Required | Description     |
-| ---- | ---- | ------------ | -------- | --------------- |
-| `id` | path | string(uuid) | true     | Organization ID |
+| Name           | In   | Type         | Required | Description     |
+| -------------- | ---- | ------------ | -------- | --------------- |
+| `organization` | path | string(uuid) | true     | Organization ID |
 
 ### Example responses