docs: document refresh token rotation and update examples

internal/handlers/auth_handler.go

@@ -52,7 +52,7 @@ type AuthTokensResponse struct {
 
 type AuthTokensDetail struct {
 	AccessToken  string          `json:"access_token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
-	RefreshToken string          `json:"refresh_token" example:"f94d4ddc7d9b4fcb9d3a2c44c400b780"`
+	RefreshToken string          `json:"refresh_token" example:"f94d4ddc7d9b4fcb9d3a2c44c400b780c3e1f1a5c2b7d4e6a0b1c2d3e4f5a6b7"`
 	User         AuthUserSummary `json:"user"`
 }
 
@@ -593,7 +593,7 @@ func (h *AuthHandler) Logout(w http.ResponseWriter, r *http.Request) {
 }
 
 // @Summary Refresh access token
-// @Description Use a refresh token to get a new access token. This endpoint allows clients to obtain a new access token using a valid refresh token without requiring user credentials.
+// @Description Use a refresh token to get a new access token. The refresh token is rotated on success, and the previous refresh token becomes invalid.
 // @Tags auth
 // @Accept json
 // @Produce json