Merge pull request #954 from gotify/logout-swagger

fix: logout to /auth/logout and swagger docs

Author: jmattheis

api/session.go

@@ -24,7 +24,34 @@ type SessionAPI struct {
 	SecureCookie  bool
 }
 
-// Login authenticates via basic auth, creates a client, sets an HttpOnly cookie, and returns user info.
+// swagger:operation POST /auth/local/login auth localLogin
+//
+// Authenticate via basic auth and create a session.
+//
+//	---
+//	consumes: [application/x-www-form-urlencoded]
+//	produces: [application/json]
+//	security:
+//	- basicAuth: []
+//	parameters:
+//	- name: name
+//	  in: formData
+//	  description: the client name to create
+//	  required: true
+//	  type: string
+//	responses:
+//	  200:
+//	    description: Ok
+//	    schema:
+//	        $ref: "#/definitions/UserExternal"
+//	    headers:
+//	      Set-Cookie:
+//	        type: string
+//	        description: session cookie
+//	  401:
+//	    description: Unauthorized
+//	    schema:
+//	        $ref: "#/definitions/Error"
 func (a *SessionAPI) Login(ctx *gin.Context) {
 	name, pass, ok := ctx.Request.BasicAuth()
 	if !ok {
@@ -65,7 +92,29 @@ func (a *SessionAPI) Login(ctx *gin.Context) {
 	})
 }
 
-// Logout deletes the client for the current session and clears the cookie.
+// swagger:operation POST /auth/logout auth logout
+//
+// End the current session.
+//
+// Clears the session cookie and deletes the associated client.
+//
+//	---
+//	produces: [application/json]
+//	security:
+//	- clientTokenHeader: []
+//	- clientTokenQuery: []
+//	- basicAuth: []
+//	responses:
+//	  200:
+//	    description: Ok
+//	    headers:
+//	      Set-Cookie:
+//	        type: string
+//	        description: cleared session cookie
+//	  400:
+//	    description: Bad Request
+//	    schema:
+//	        $ref: "#/definitions/Error"
 func (a *SessionAPI) Logout(ctx *gin.Context) {
 	auth.SetCookie(ctx.Writer, "", -1, a.SecureCookie)
 

api/session_test.go

@@ -112,7 +112,7 @@ func (s *SessionSuite) Test_Logout_Success() {
 	builder := s.db.User(5)
 	builder.ClientWithToken(1, "Ctesttoken12345")
 
-	s.ctx.Request = httptest.NewRequest("POST", "/auth/local/logout", nil)
+	s.ctx.Request = httptest.NewRequest("POST", "/auth/logout", nil)
 	test.WithUser(s.ctx, 5)
 	s.ctx.Set("tokenid", "Ctesttoken12345")
 

docs/spec.json

@@ -587,6 +587,96 @@
         }
       }
     },
+    "/auth/local/login": {
+      "post": {
+        "security": [
+          {
+            "basicAuth": []
+          }
+        ],
+        "consumes": [
+          "application/x-www-form-urlencoded"
+        ],
+        "produces": [
+          "application/json"
+        ],
+        "tags": [
+          "auth"
+        ],
+        "summary": "Authenticate via basic auth and create a session.",
+        "operationId": "localLogin",
+        "parameters": [
+          {
+            "type": "string",
+            "description": "the client name to create",
+            "name": "name",
+            "in": "formData",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Ok",
+            "schema": {
+              "$ref": "#/definitions/UserExternal"
+            },
+            "headers": {
+              "Set-Cookie": {
+                "type": "string",
+                "description": "session cookie"
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "schema": {
+              "$ref": "#/definitions/Error"
+            }
+          }
+        }
+      }
+    },
+    "/auth/logout": {
+      "post": {
+        "security": [
+          {
+            "clientTokenHeader": []
+          },
+          {
+            "clientTokenQuery": []
+          },
+          {
+            "basicAuth": []
+          }
+        ],
+        "description": "Clears the session cookie and deletes the associated client.",
+        "produces": [
+          "application/json"
+        ],
+        "tags": [
+          "auth"
+        ],
+        "summary": "End the current session.",
+        "operationId": "logout",
+        "responses": {
+          "200": {
+            "description": "Ok",
+            "headers": {
+              "Set-Cookie": {
+                "type": "string",
+                "description": "cleared session cookie"
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "schema": {
+              "$ref": "#/definitions/Error"
+            }
+          }
+        }
+      }
+    },
     "/auth/oidc/callback": {
       "get": {
         "description": "Exchanges the authorization code for tokens, resolves the user,\ncreates a gotify client, sets a session cookie, and redirects to the UI.",

router/router.go

@@ -230,7 +230,7 @@ func Create(db *database.GormDatabase, vInfo *model.VersionInfo, conf *config.Co
 
 		clientAuth.POST("current/user/password", userHandler.ChangePassword)
 
-		clientAuth.POST("/auth/local/logout", sessionHandler.Logout)
+		clientAuth.POST("/auth/logout", sessionHandler.Logout)
 	}
 
 	authAdmin := g.Group("/user")

ui/src/CurrentUser.ts

@@ -119,9 +119,7 @@ export class CurrentUser {
             runInAction(() => {
                 this.loggedIn = false;
             });
-            await axios
-                .post(config.get('url') + 'auth/local/logout')
-                .catch(() => Promise.resolve());
+            await axios.post(config.get('url') + 'auth/logout').catch(() => Promise.resolve());
         }
     };