docs: improve authentication page (#5567)

* docs: improve authentication page

* Update docs/admin/automation.md

Co-authored-by: Mathias Fredriksson <mafredri@gmail.com>

* Update docs/admin/automation.md

Co-authored-by: Mathias Fredriksson <mafredri@gmail.com>

* Fix

* Fix

Co-authored-by: Mathias Fredriksson <mafredri@gmail.com>

docs/admin/automation.md

@@ -2,13 +2,9 @@
 
 We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md).
 
-## Tokens
+## Authentication
 
-Long-lived tokens can be generated to perform actions on behalf of your user account:
-
-```console
-coder tokens create
-```
+Coder uses authentication tokens to grant machine users access to the REST API. Follow the [Authentication](../api/authentication.md) page to learn how to generate long-lived tokens.
 
 ## CLI
 
@@ -23,14 +19,13 @@ coder workspaces ls
 
 ## REST API
 
-You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header.
+You can review the [API reference](../api/index.md) to find the necessary routes and payload. Alternatively, you can enable the [Swagger](https://swagger.io/) endpoint to read the documentation and do requests against the API:
 
 ```console
-curl 'https://dev.coder.com/api/v2/workspaces' \
-  -H 'Coder-Session-Token: *****'
+coder server --swagger-enable
 ```
 
-> At this time, we do not publish an API reference. However, [codersdk](https://github.com/coder/coder/tree/main/codersdk) can be grepped to find the necessary routes and payloads.
+By default, the local Swagger endpoint is http://localhost:3000/swagger.
 
 ## Golang SDK
 

docs/api/authentication.md

@@ -1,4 +1,14 @@
 # Authentication
 
-- API Key (CoderSessionToken)
-  - Parameter Name: **Coder-Session-Token**, in: header.
+Long-lived tokens can be generated to perform actions on behalf of your user account:
+
+```console
+coder tokens create
+```
+
+You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header.
+
+```console
+curl 'http://coder-server:8080/api/v2/workspaces' \
+  -H 'Coder-Session-Token: *****'
+```

scripts/apidocgen/markdown-template/security.def

@@ -1,27 +1,15 @@
 <!-- APIDOCGEN: BEGIN SECTION -->
-{{= data.tags.section }}# Authentication
-{{ for (var s in data.api.components.securitySchemes) { }}
-{{ var sd = data.api.components.securitySchemes[s]; }}
-{{? sd.type == 'apiKey' }}
-- API Key ({{=s}})
-  - Parameter Name: **{{=sd.name}}**, in: {{=sd.in}}. {{=sd.description || ''}}
-{{?}}
-{{? sd.type == 'http'}}
-- HTTP Authentication, scheme: {{=sd.scheme}}{{? sd.description }}<br/>{{=sd.description}}{{?}}
-{{?}}
-{{? sd.type == 'oauth2'}}
-- oAuth2 authentication. {{=sd.description || ''}}
-{{ for (var f in sd.flows) { }}
-{{ var flow = sd.flows[f]; }}
-    - Flow: {{=f}}
-{{? flow.authorizationUrl}}    - Authorization URL = [{{=flow.authorizationUrl}}]({{=flow.authorizationUrl}}){{?}}
-{{? flow.tokenUrl}}    - Token URL = [{{=flow.tokenUrl}}]({{=flow.tokenUrl}}){{?}}
-{{? flow.scopes && Object.keys(flow.scopes).length}}
-|Scope|Scope Description|
-|---|---|
-{{ for (var sc in flow.scopes) { }}|{{=sc}}|{{=data.utils.join(flow.scopes[sc])}}|
-{{ } /* of scopes */ }}
-{{?}}
-{{ } /* of flows */ }}
-{{?}}
-{{ } /* of securitySchemes */ }}
+# Authentication
+
+Long-lived tokens can be generated to perform actions on behalf of your user account:
+
+```console
+coder tokens create
+```
+
+You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header.
+
+```console
+curl 'http://coder-server:8080/api/v2/workspaces' \
+  -H 'Coder-Session-Token: *****'
+```