Update swagger

coder · Emyrk · Dec 6, 2023 · Nov 29, 2023 · Nov 30, 2023 · Nov 29, 2023
commit 919e490c259325986f6755b49979d5847b858e37
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/coderd.go b/coderd/coderd.go
@@ -665,7 +665,7 @@ func New(options *Options) *API {
 				apiKeyMiddleware,
 			)
 			// Get without a specific external auth ID will return all external auths.
-			r.Get("/", api.userExternalAuths)
+			r.Get("/", api.listUserExternalAuths)
 			r.Route("/{externalauth}", func(r chi.Router) {
 				r.Use(
 					httpmw.ExtractExternalAuthParam(options.ExternalAuthConfigs),

diff --git a/coderd/database/dbmem/dbmem.go b/coderd/database/dbmem/dbmem.go
@@ -1027,7 +1027,7 @@ func (*FakeQuerier) DeleteCoordinator(context.Context, uuid.UUID) error {
 	return ErrUnimplemented
 }
 
-func (q *FakeQuerier) DeleteExternalAuthLink(ctx context.Context, arg database.DeleteExternalAuthLinkParams) error {
+func (q *FakeQuerier) DeleteExternalAuthLink(_ context.Context, arg database.DeleteExternalAuthLinkParams) error {
 	err := validateDatabaseType(arg)
 	if err != nil {
 		return err

diff --git a/coderd/externalauth.go b/coderd/externalauth.go
@@ -21,8 +21,8 @@ import (
 // @Summary Get external auth by ID
 // @ID get-external-auth-by-id
 // @Security CoderSessionToken
-// @Produce json
 // @Tags Git
+// @Produce json
 // @Param externalauth path string true "Git Provider ID" format(string)
 // @Success 200 {object} codersdk.ExternalAuth
 // @Router /external-auth/{externalauth} [get]
@@ -78,14 +78,15 @@ func (api *API) externalAuthByID(w http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, w, http.StatusOK, res)
 }
 
+// deleteExternalAuthByID only deletes the link on the Coder side, does not revoke the token on the provider side.
+//
 // @Summary Delete external auth user link by ID
 // @ID delete-external-auth-user-link-by-id
 // @Security CoderSessionToken
-// @Produce json
-// @Param externalauth path string true "Git Provider ID" format(string)
+// @Tags Git
 // @Success 200
+// @Param externalauth path string true "Git Provider ID" format(string)
 // @Router /external-auth/{externalauth} [delete]
-// deleteExternalAuthByID only deletes the link on the Coder side, does not revoke the token on the provider side.
 func (api *API) deleteExternalAuthByID(w http.ResponseWriter, r *http.Request) {
 	config := httpmw.ExternalAuthParam(r)
 	apiKey := httpmw.APIKey(r)
@@ -309,14 +310,17 @@ func (api *API) externalAuthCallback(externalAuthConfig *externalauth.Config) ht
 	}
 }
 
+// listUserExternalAuths lists all external auths available to a user and
+// their auth links if they exist.
+//
 // @Summary Get user external auths
 // @ID get-user-external-auths
 // @Security CoderSessionToken
 // @Produce json
-// @Tags Users
+// @Tags Git
 // @Success 200 {object} codersdk.ExternalAuthLink
-// @Router /users/external-auths [get]
-func (api *API) userExternalAuths(rw http.ResponseWriter, r *http.Request) {
+// @Router /external-auth [get]
+func (api *API) listUserExternalAuths(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	key := httpmw.APIKey(r)
 
@@ -335,7 +339,9 @@ func (api *API) userExternalAuths(rw http.ResponseWriter, r *http.Request) {
 
 	// Note: It would be really nice if we could cfg.Validate() the links and
 	// return their authenticated status. To do this, we would also have to
-	// refresh expired tokens too.
+	// refresh expired tokens too. For now, I do not want to cause the excess
+	// traffic on this request, so the user will have to do this with a separate
+	// call.
 	httpapi.Write(ctx, rw, http.StatusOK, codersdk.ListUserExternalAuthResponse{
 		Providers: ExternalAuthConfigs(api.ExternalAuthConfigs),
 		Links:     db2sdk.ExternalAuths(links),

diff --git a/codersdk/externalauth.go b/codersdk/externalauth.go
@@ -62,7 +62,8 @@ type ListUserExternalAuthResponse struct {
 	Providers []ExternalAuthLinkProvider `json:"providers"`
 	// Links are all the authenticated links for the user.
 	// If a link has a provider ID that does not exist, then that provider
-	// is no longer configured, rendering it unusable.
+	// is no longer configured, rendering it unusable. It is still valuable
+	// to include these links so that the user can unlink them.
 	Links []ExternalAuthLink `json:"links"`
 }
 

diff --git a/docs/api/default.md b/docs/api/default.md
diff --git a/docs/api/git.md b/docs/api/git.md
diff --git a/docs/api/users.md b/docs/api/users.md
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -523,10 +523,6 @@
           "title": "Debug",
           "path": "./api/debug.md"
         },
-        {
-          "title": "Default",
-          "path": "./api/default.md"
-        },
         {
           "title": "Enterprise",
           "path": "./api/enterprise.md"