docs: API enterprise (#5625)

* 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

* WIP

* WIP

* Users

* Logout

* User profile

* Status suspend activate

* User roles

* User tokens

* Keys

* SSH key

* All

* Typo

* Fix

* Entitlements

* Groups

* SCIM

* Fix

* Fix

* Clean templates

* Sort API pages

* Fix: HashedSecret

* General is first

codersdk/apikey.go

@@ -10,9 +10,9 @@ import (
 	"github.com/google/uuid"
 )
 
+// APIKey: do not ever return the HashedSecret
 type APIKey struct {
-	ID string `json:"id" validate:"required"`
-	// NOTE: do not ever return the HashedSecret
+	ID              string      `json:"id" validate:"required"`
 	UserID          uuid.UUID   `json:"user_id" validate:"required" format:"uuid"`
 	LastUsed        time.Time   `json:"last_used" validate:"required" format:"date-time"`
 	ExpiresAt       time.Time   `json:"expires_at" validate:"required" format:"date-time"`

codersdk/groups.go

@@ -17,9 +17,9 @@ type CreateGroupRequest struct {
 }
 
 type Group struct {
-	ID             uuid.UUID `json:"id"`
+	ID             uuid.UUID `json:"id" format:"uuid"`
 	Name           string    `json:"name"`
-	OrganizationID uuid.UUID `json:"organization_id"`
+	OrganizationID uuid.UUID `json:"organization_id" format:"uuid"`
 	Members        []User    `json:"members"`
 	AvatarURL      string    `json:"avatar_url"`
 	QuotaAllowance int       `json:"quota_allowance"`

codersdk/licenses.go

@@ -16,8 +16,8 @@ type AddLicenseRequest struct {
 
 type License struct {
 	ID         int32     `json:"id"`
-	UUID       uuid.UUID `json:"uuid"`
-	UploadedAt time.Time `json:"uploaded_at"`
+	UUID       uuid.UUID `json:"uuid" format:"uuid"`
+	UploadedAt time.Time `json:"uploaded_at" format:"date-time"`
 	// Claims are the JWT claims asserted by the license.  Here we use
 	// a generic string map to ensure that all data from the server is
 	// parsed verbatim, not just the fields this version of Coder

codersdk/provisionerdaemons.go

@@ -37,9 +37,9 @@ const (
 )
 
 type ProvisionerDaemon struct {
-	ID           uuid.UUID         `json:"id"`
-	CreatedAt    time.Time         `json:"created_at"`
-	UpdatedAt    sql.NullTime      `json:"updated_at"`
+	ID           uuid.UUID         `json:"id" format:"uuid"`
+	CreatedAt    time.Time         `json:"created_at" format:"date-time"`
+	UpdatedAt    sql.NullTime      `json:"updated_at" format:"date-time"`
 	Name         string            `json:"name"`
 	Provisioners []ProvisionerType `json:"provisioners"`
 	Tags         map[string]string `json:"tags"`

codersdk/replicas.go

@@ -12,16 +12,16 @@ import (
 
 type Replica struct {
 	// ID is the unique identifier for the replica.
-	ID uuid.UUID `json:"id"`
+	ID uuid.UUID `json:"id" format:"uuid"`
 	// Hostname is the hostname of the replica.
 	Hostname string `json:"hostname"`
-	// CreatedAt is when the replica was first seen.
-	CreatedAt time.Time `json:"created_at"`
+	// CreatedAt is the timestamp when the replica was first seen.
+	CreatedAt time.Time `json:"created_at" format:"date-time"`
 	// RelayAddress is the accessible address to relay DERP connections.
 	RelayAddress string `json:"relay_address"`
 	// RegionID is the region of the replica.
 	RegionID int32 `json:"region_id"`
-	// Error is the error.
+	// Error is the replica error.
 	Error string `json:"error"`
 	// DatabaseLatency is the latency in microseconds to the database.
 	DatabaseLatency int32 `json:"database_latency"`

codersdk/templates.go

@@ -60,12 +60,12 @@ type TemplateACL struct {
 
 type TemplateGroup struct {
 	Group
-	Role TemplateRole `json:"role"`
+	Role TemplateRole `json:"role" enums:"admin,use"`
 }
 
 type TemplateUser struct {
 	User
-	Role TemplateRole `json:"role"`
+	Role TemplateRole `json:"role" enums:"admin,use"`
 }
 
 type UpdateTemplateACL struct {