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

scripts/apidocgen/generate.sh

@@ -20,7 +20,7 @@ log "Use temporary file: ${API_MD_TMP_FILE}"
 pushd "${PROJECT_ROOT}"
 go run github.com/swaggo/swag/cmd/swag@v1.8.9 init \
 	--generalInfo="coderd.go" \
-	--dir="./coderd,./codersdk" \
+	--dir="./coderd,./codersdk,./enterprise/coderd" \
 	--output="./coderd/apidoc" \
 	--outputTypes="go,json" \
 	--parseDependency=true

scripts/apidocgen/markdown-template/debug.def

@@ -1 +0,0 @@
-{{= data.utils.inspect(data) }}

scripts/apidocgen/markdown-template/main.dot

@@ -53,12 +53,16 @@
 
 		const countUppercase = words[0].length - words[0].replace(/[A-Z]/g, '').length;
 		if (countUppercase > 1) {
-			let displayName = p.displayName.replace(/» \*\*additionalProperties\*\*/g, "It");
+			let displayName = p.displayName.replace(/» \*\*additionalProperties\*\*/g, "It").replace("» ", "");
 			displayName = displayName.charAt(0).toUpperCase() + displayName.replace(/_/g, " ").toLowerCase().slice(1);
 			description = displayName + " " + words.slice(1).join(' ');
 		}
 		return correctLetterCase(description);
 	}
+
+	/* Export functions that are used by other template partials. */
+	data.functions = {};
+	data.functions.renderDescription = renderDescription;
 }}
 
 {{? data.api.components && data.api.components.securitySchemes }}{{#def.security}}{{?}}

scripts/apidocgen/markdown-template/responses.def

@@ -98,7 +98,7 @@ Status Code **{{=response.status}}**
 {{?}}
 |Name|Type|Required|Restrictions|Description|
 |---|---|---|---|---|
-{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
+{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=data.functions.renderDescription(p)}}|
 {{~}}
 {{~}}
 {{?}}

scripts/apidocgen/postprocess/main.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"path"
 	"regexp"
+	"sort"
 	"strings"
 
 	"golang.org/x/xerrors"
@@ -132,6 +133,18 @@ func writeDocs(sections [][]byte) error {
 		})
 	}
 
+	// Sort API pages
+	// The "General" section is expected to be always first.
+	sort.Slice(mdFiles, func(i, j int) bool {
+		if mdFiles[i].title == "General" {
+			return true // "General" < ... - sorted
+		}
+		if mdFiles[j].title == "General" {
+			return false // ... < "General" - not sorted
+		}
+		return sort.StringsAreSorted([]string{mdFiles[i].title, mdFiles[j].title})
+	})
+
 	// Update manifest.json
 	type route struct {
 		Title       string  `json:"title,omitempty"`