docs: audit, deploymentconfig, files, parameters (#5506)

* docs: audit, deploymentconfig, files, parameters

* Fix: mark as binary

* Fix: show format in docs

* Fix: use .swaggo

* Fix: swagger notice

* Swagger notice

coderd/audit.go

@@ -24,6 +24,17 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Get audit logs
+// @ID get-audit-logs
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Audit
+// @Param q query string true "Search query"
+// @Param after_id query string false "After ID" format(uuid)
+// @Param limit query int false "Page limit"
+// @Param offset query int false "Page offset"
+// @Success 200 {object} codersdk.AuditLogResponse
+// @Router /audit [get]
 func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	if !api.Authorize(r, rbac.ActionRead, rbac.ResourceAuditLog) {
@@ -77,6 +88,14 @@ func (api *API) auditLogs(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// @Summary Generate fake audit log
+// @ID generate-fake-audit-logs
+// @Security CoderSessionToken
+// @Accept json
+// @Tags Audit
+// @Param request body codersdk.CreateTestAuditLogRequest true "Audit log request"
+// @Success 204
+// @Router /audit/testgenerate [post]
 func (api *API) generateFakeAuditLog(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	if !api.Authorize(r, rbac.ActionCreate, rbac.ResourceAuditLog) {

coderd/deploymentconfig.go

@@ -7,6 +7,13 @@ import (
 	"github.com/coder/coder/coderd/rbac"
 )
 
+// @Summary Get deployment config
+// @ID get-deployment-config
+// @Security CoderSessionToken
+// @Produce json
+// @Tags General
+// @Success 200 {object} codersdk.DeploymentConfig
+// @Router /config/deployment [get]
 func (api *API) deploymentConfig(rw http.ResponseWriter, r *http.Request) {
 	if !api.Authorize(r, rbac.ActionRead, rbac.ResourceDeploymentConfig) {
 		httpapi.Forbidden(rw)

coderd/files.go

@@ -23,6 +23,17 @@ const (
 	tarMimeType = "application/x-tar"
 )
 
+// @Summary Upload file
+// @Description Swagger notice: Swagger 2.0 doesn't support file upload with a `content-type` different than `application/x-www-form-urlencoded`.
+// @ID update-file
+// @Security CoderSessionToken
+// @Produce json
+// @Accept application/x-tar
+// @Tags Files
+// @Param Content-Type header string true "Content-Type must be `application/x-tar`" default(application/x-tar)
+// @Param file formData file true "File to be uploaded"
+// @Success 201 {object} codersdk.UploadResponse
+// @Router /files [post]
 func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	apiKey := httpmw.APIKey(r)
@@ -88,6 +99,13 @@ func (api *API) postFile(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// @Summary Get file by ID
+// @ID get-file-by-id
+// @Security CoderSessionToken
+// @Tags Files
+// @Param fileID path string true "File ID" format(uuid)
+// @Success 200
+// @Router /files/{fileID} [get]
 func (api *API) fileByID(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

coderd/parameters.go

@@ -18,6 +18,17 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Create parameter
+// @ID create-parameter
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Parameters
+// @Param request body codersdk.CreateParameterRequest true "Parameter request"
+// @Param scope path string true "Scope" Enums(template,workspace,import_job)
+// @Param id path string true "ID" format(uuid)
+// @Success 201 {object} codersdk.Parameter
+// @Router /parameters/{scope}/{id} [post]
 func (api *API) postParameter(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	scope, scopeID, valid := readScopeAndID(ctx, rw, r)
@@ -78,6 +89,15 @@ func (api *API) postParameter(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusCreated, convertParameterValue(parameterValue))
 }
 
+// @Summary Get parameters
+// @ID get-parameters
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Parameters
+// @Param scope path string true "Scope" Enums(template,workspace,import_job)
+// @Param id path string true "ID" format(uuid)
+// @Success 200 {array} codersdk.Parameter
+// @Router /parameters/{scope}/{id} [get]
 func (api *API) parameters(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	scope, scopeID, valid := readScopeAndID(ctx, rw, r)
@@ -116,6 +136,16 @@ func (api *API) parameters(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiParameterValues)
 }
 
+// @Summary Delete parameter
+// @ID delete-parameter
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Parameters
+// @Param scope path string true "Scope" Enums(template,workspace,import_job)
+// @Param id path string true "ID" format(uuid)
+// @Param name path string true "Name"
+// @Success 200 {object} codersdk.Response
+// @Router /parameters/{scope}/{id}/{name} [delete]
 func (api *API) deleteParameter(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	scope, scopeID, valid := readScopeAndID(ctx, rw, r)

coderd/templates.go

@@ -478,7 +478,7 @@ func (api *API) templateByOrganizationAndName(rw http.ResponseWriter, r *http.Re
 // @Tags Templates
 // @Param id path string true "Template ID" format(uuid)
 // @Success 200 {object} codersdk.Template
-// @Router /templates/{id} [get]
+// @Router /templates/{id} [patch]
 func (api *API) patchTemplateMeta(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()