docs: API templateversions, templates, members, organizations (#5546)

* docs: audit, deploymentconfig, files, parameters

* Swagger comments in workspacebuilds.go

* structs in workspacebuilds.go

* workspaceagents: instance identity

* workspaceagents.go in progress

* workspaceagents.go in progress

* Agents

* workspacebuilds.go

* /workspaces

* templates.go, templateversions.go

* templateversion.go in progress

* cancel

* templateversions

* wip

* Merge

* x-apidocgen

* NullTime hack not needed anymore

* Fix: x-apidocgen

* Members

* Fixes

* Fix

coderd/coderd.go

@@ -431,7 +431,6 @@ func New(options *Options) *API {
 				apiKeyMiddleware,
 				httpmw.ExtractTemplateVersionParam(options.Database),
 			)
-
 			r.Get("/", api.templateVersion)
 			r.Patch("/cancel", api.patchCancelTemplateVersion)
 			r.Get("/schema", api.templateVersionSchema)

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

coderd/organizations.go

@@ -16,6 +16,14 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Get organization by ID
+// @ID get-organization-by-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Organizations
+// @Param organization path string true "Organization ID" format(uuid)
+// @Success 200 {object} codersdk.Organization
+// @Router /organizations/{organization} [get]
 func (api *API) organization(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)
@@ -29,6 +37,14 @@ func (api *API) organization(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertOrganization(organization))
 }
 
+// @Summary Create organization
+// @ID create-organization
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Organizations
+// @Param request body codersdk.CreateOrganizationRequest true "Create organization request"
+// @Success 201 {object} codersdk.Organization
+// @Router /organizations [post]
 func (api *API) postOrganizations(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	apiKey := httpmw.APIKey(r)

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

coderd/templates.go

@@ -138,9 +138,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) {
@@ -336,7 +336,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()
@@ -402,9 +402,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)
@@ -588,6 +588,14 @@ func (api *API) patchTemplateMeta(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, api.convertTemplate(updated, count, createdByNameMap[updated.ID.String()]))
 }
 
+// @Summary Get template DAUs by ID
+// @ID get-template-daus-by-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param id path string true "Template ID" format(uuid)
+// @Success 200 {object} codersdk.TemplateDAUsResponse
+// @Router /templates/{id}/daus [get]
 func (api *API) templateDAUs(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	template := httpmw.TemplateParam(r)
@@ -606,6 +614,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()

coderd/templateversions.go

@@ -28,6 +28,14 @@ import (
 	"github.com/coder/coder/examples"
 )
 
+// @Summary Get template version by ID
+// @ID get-template-version-by-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Success 200 {object} codersdk.TemplateVersion
+// @Router /templateversions/{templateversion} [get]
 func (api *API) templateVersion(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var (
@@ -61,6 +69,14 @@ func (api *API) templateVersion(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertTemplateVersion(templateVersion, convertProvisionerJob(job), user))
 }
 
+// @Summary Cancel template version by ID
+// @ID cancel-template-version-by-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Success 200 {object} codersdk.Response
+// @Router /templateversions/{templateversion}/cancel [patch]
 func (api *API) patchCancelTemplateVersion(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var (
@@ -116,6 +132,14 @@ func (api *API) patchCancelTemplateVersion(rw http.ResponseWriter, r *http.Reque
 	})
 }
 
+// @Summary Get schema by template version
+// @ID get-schema-by-template-version
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Success 200 {array} codersdk.ParameterSchema
+// @Router /templateversions/{templateversion}/schema [get]
 func (api *API) templateVersionSchema(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var (
@@ -168,6 +192,14 @@ func (api *API) templateVersionSchema(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiSchemas)
 }
 
+// @Summary Get parameters by template version
+// @ID get-parameters-by-template-version
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Success 200 {array} parameter.ComputedValue
+// @Router /templateversions/{templateversion}/parameters [get]
 func (api *API) templateVersionParameters(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var (
@@ -213,6 +245,16 @@ func (api *API) templateVersionParameters(rw http.ResponseWriter, r *http.Reques
 	httpapi.Write(ctx, rw, http.StatusOK, values)
 }
 
+// @Summary Create template version dry-run
+// @ID create-template-version-dry-run
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Param request body codersdk.CreateTemplateVersionDryRunRequest true "Dry-run request"
+// @Success 201 {object} codersdk.ProvisionerJob
+// @Router /templateversions/{templateversion}/dry-run [post]
 func (api *API) postTemplateVersionDryRun(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var (
@@ -308,6 +350,16 @@ func (api *API) postTemplateVersionDryRun(rw http.ResponseWriter, r *http.Reques
 	httpapi.Write(ctx, rw, http.StatusCreated, convertProvisionerJob(provisionerJob))
 }
 
+// @Summary Get template version dry-run by job ID
+// @ID get-template-version-dry-run-by-job-id
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Param jobid path string true "Job ID" format(uuid)
+// @Success 200 {object} codersdk.ProvisionerJob
+// @Router /templateversions/{templateversion}/dry-run/{jobid} [get]
 func (api *API) templateVersionDryRun(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	job, ok := api.fetchTemplateVersionDryRunJob(rw, r)
@@ -318,6 +370,15 @@ func (api *API) templateVersionDryRun(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertProvisionerJob(job))
 }
 
+// @Summary Get template version dry-run resources by job ID
+// @ID get-template-version-dry-run-resources-by-job-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Param jobid path string true "Job ID" format(uuid)
+// @Success 200 {array} codersdk.WorkspaceResource
+// @Router /templateversions/{templateversion}/dry-run/{jobid}/resources [get]
 func (api *API) templateVersionDryRunResources(rw http.ResponseWriter, r *http.Request) {
 	job, ok := api.fetchTemplateVersionDryRunJob(rw, r)
 	if !ok {
@@ -327,6 +388,18 @@ func (api *API) templateVersionDryRunResources(rw http.ResponseWriter, r *http.R
 	api.provisionerJobResources(rw, r, job)
 }
 
+// @Summary Get template version dry-run logs by job ID
+// @ID get-template-version-dry-run-logs-by-job-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Param jobid path string true "Job ID" format(uuid)
+// @Param before query int false "Before Unix timestamp"
+// @Param after query int false "After Unix timestamp"
+// @Param follow query bool false "Follow log stream"
+// @Success 200 {array} codersdk.ProvisionerJobLog
+// @Router /templateversions/{templateversion}/dry-run/{jobid}/logs [get]
 func (api *API) templateVersionDryRunLogs(rw http.ResponseWriter, r *http.Request) {
 	job, ok := api.fetchTemplateVersionDryRunJob(rw, r)
 	if !ok {
@@ -336,6 +409,14 @@ func (api *API) templateVersionDryRunLogs(rw http.ResponseWriter, r *http.Reques
 	api.provisionerJobLogs(rw, r, job)
 }
 
+// @Summary Cancel template version dry-run by job ID
+// @ID cancel-template-version-dry-run-by-job-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Success 200 {object} codersdk.Response
+// @Router /templateversions/{templateversion}/dry-run/{jobid}/cancel [patch]
 func (api *API) patchTemplateVersionDryRunCancel(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	templateVersion := httpmw.TemplateVersionParam(r)
@@ -454,6 +535,14 @@ func (api *API) fetchTemplateVersionDryRunJob(rw http.ResponseWriter, r *http.Re
 	return job, true
 }
 
+// @Summary List template versions by template ID
+// @ID list-template-versions-by-template-ID
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param id path string true "Template ID" format(uuid)
+// @Success 200 {array} codersdk.TemplateVersion
+// @Router /templates/{id}/versions [get]
 func (api *API) templateVersionsByTemplate(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	template := httpmw.TemplateParam(r)
@@ -551,6 +640,15 @@ func (api *API) templateVersionsByTemplate(rw http.ResponseWriter, r *http.Reque
 	httpapi.Write(ctx, rw, http.StatusOK, apiVersions)
 }
 
+// @Summary Get template version by template ID and name
+// @ID get-template-version-by-template-id-and-name
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param id path string true "Template ID" format(uuid)
+// @Param templateversionname path string true "Template version name"
+// @Success 200 {array} codersdk.TemplateVersion
+// @Router /templates/{id}/versions/{templateversionname} [get]
 func (api *API) templateVersionByName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	template := httpmw.TemplateParam(r)
@@ -601,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)
@@ -643,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}/previous [get]
 func (api *API) previousTemplateVersionByOrganizationAndName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)
@@ -708,6 +824,16 @@ func (api *API) previousTemplateVersionByOrganizationAndName(rw http.ResponseWri
 	httpapi.Write(ctx, rw, http.StatusOK, convertTemplateVersion(previousTemplateVersion, convertProvisionerJob(job), user))
 }
 
+// @Summary Update active template version by template ID
+// @ID update-active-template-version-by-template-ID
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Templates
+// @Param request body codersdk.UpdateActiveTemplateVersion true "Modified template version"
+// @Param id path string true "Template ID" format(uuid)
+// @Success 200 {object} codersdk.Response
+// @Router /templates/{id}/versions [patch]
 func (api *API) patchActiveTemplateVersion(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()
@@ -782,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()
@@ -1067,6 +1204,15 @@ func (api *API) postTemplateVersionsByOrganization(rw http.ResponseWriter, r *ht
 	httpapi.Write(ctx, rw, http.StatusCreated, convertTemplateVersion(templateVersion, convertProvisionerJob(provisionerJob), user))
 }
 
+// @Summary Get resources by template version
+// @ID get-resources-by-template-version
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Success 200 {array} codersdk.WorkspaceResource
+// @Router /templateversions/{templateversion}/resources [get]
+//
 // templateVersionResources returns the workspace agent resources associated
 // with a template version. A template can specify more than one resource to be
 // provisioned, each resource can have an agent that dials back to coderd. The
@@ -1095,6 +1241,18 @@ func (api *API) templateVersionResources(rw http.ResponseWriter, r *http.Request
 	api.provisionerJobResources(rw, r, job)
 }
 
+// @Summary Get logs by template version
+// @ID get-logs-by-template-version
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Templates
+// @Param templateversion path string true "Template version ID" format(uuid)
+// @Param before query int false "Before Unix timestamp"
+// @Param after query int false "After Unix timestamp"
+// @Param follow query bool false "Follow log stream"
+// @Success 200 {array} codersdk.ProvisionerJobLog
+// @Router /templateversions/{templateversion}/logs [get]
+//
 // templateVersionLogs returns the logs returned by the provisioner for the given
 // template version. These logs are only associated with the template version,
 // and not any build logs for a workspace.

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 (