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

scripts/apidocgen/markdown-template/code_shell.dot

@@ -1,4 +1,8 @@
 # Example request using curl
 curl -X {{=data.methodUpper}} http://coder-server:8080{{=data.url}}{{=data.requiredQueryString}}{{?data.allHeaders.length}} \{{?}}
-{{~data.allHeaders :p:index}}  -H '{{=p.name}}: {{=p.exampleValues.object}}'{{?index < data.allHeaders.length-1}} \
+{{~data.allHeaders :p:index}}{{
+	if (p.name == "Content-Type" && p.exampleValues.object == "application/x-www-form-urlencoded") {
+		continue;
+	}
+}}  -H '{{=p.name}}: {{=p.exampleValues.object}}'{{?index < data.allHeaders.length-1}} \
 {{?}}{{~}}

scripts/apidocgen/markdown-template/main.dot

@@ -5,9 +5,6 @@
 		}
 
 		const pRef = p.$ref.replace("#/components/schemas/","");
-		if (pRef == "codersdk.NullTime") {
-			return "string(time) or `null`";
-		}
 		return "[" + pRef + "](#" + pRef.replace(".","").toLowerCase() + ")";
 	}
 

scripts/apidocgen/markdown-template/operation.dot

@@ -1,7 +1,17 @@
 {{
 	function renderCodeSample(data) {
 		const originalCodeSample = data.utils.getCodeSamples(data);
-		return originalCodeSample.replace("\n```\n", "```\n")
+		return originalCodeSample.replace("\n```\n", "```\n");
+	}
+
+	function renderDescription(data) {
+		if (!data.operation.description) {
+			return "";
+		}
+		if (data.operation.description.startsWith("Swagger notice:")) {
+			return "";
+		}
+		return data.operation.description;
 	}
 }}
 {{= data.tags.section }}
@@ -27,7 +37,7 @@
 
 {{? data.operation.summary && !data.options.tocSummary}}*{{= data.operation.summary }}*{{?}}
 
-{{? data.operation.description}}{{= data.operation.description }}{{?}}
+{{= renderDescription(data)}}
 
 {{? data.operation.requestBody}}
 > Body parameter
@@ -48,7 +58,5 @@
 {{ data.security = data.operation.security ? data.operation.security : data.api.security; }}
 {{? data.security && data.security.length }}
 {{#def.authentication}}
-{{??}}
-{{#def.authentication_none}}
 {{?}}
 {{= data.tags.endSection }}

scripts/apidocgen/markdown-template/parameters.def

@@ -5,6 +5,9 @@
 		const href = aType.replace(".","").toLowerCase();
 		return "[" + aType + "](schemas.md#" + href + ")";
 	}
+	if (p.safeType == 'string(binary)') {
+		return 'binary';
+	}
 	return p.safeType;
   }
 }}

scripts/apidocgen/markdown-template/responses.def

@@ -32,6 +32,18 @@
 		let displayName = p.displayName.replace("**additionalProperties**", "[any property]");
 		return displayName;
 	}
+
+	function renderResponsePropertyType(p) {
+		if (p.$ref) {
+			return '`' + p.$ref + '`';
+		}
+
+		if (p.type == 'array') {
+			return p.type;
+		}
+
+		return p.safeType;
+	}
 }}
 {{ data.responses = data.utils.getResponses(data); }}
 {{ data.responseSchemas = false; }}
@@ -85,7 +97,7 @@ Status Code **{{=response.status}}**
 {{?}}
 |Name|Type|Required|Restrictions|Description|
 |---|---|---|---|---|
-{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
+{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
 {{~}}
 {{~}}
 {{?}}