From 3273048f686ab9b35fc9838d62e95e974b766750 Mon Sep 17 00:00:00 2001 From: Gauthier Roebroeck Date: Mon, 17 Feb 2025 14:59:34 +0800 Subject: [PATCH] docs(api): add servers and logout endpoint --- .../swagger/OpenApiConfiguration.kt | 57 ++++++++++++++++--- .../interfaces/api/rest/LoginController.kt | 2 +- 2 files changed, 49 insertions(+), 10 deletions(-) diff --git a/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/OpenApiConfiguration.kt b/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/OpenApiConfiguration.kt index fe87d540..4804fc2d 100644 --- a/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/OpenApiConfiguration.kt +++ b/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/OpenApiConfiguration.kt @@ -3,9 +3,16 @@ package org.gotson.komga.infrastructure.swagger import io.swagger.v3.oas.models.Components import io.swagger.v3.oas.models.ExternalDocumentation import io.swagger.v3.oas.models.OpenAPI +import io.swagger.v3.oas.models.Operation +import io.swagger.v3.oas.models.PathItem import io.swagger.v3.oas.models.info.Info import io.swagger.v3.oas.models.info.License +import io.swagger.v3.oas.models.responses.ApiResponse +import io.swagger.v3.oas.models.responses.ApiResponses import io.swagger.v3.oas.models.security.SecurityScheme +import io.swagger.v3.oas.models.servers.Server +import io.swagger.v3.oas.models.servers.ServerVariable +import io.swagger.v3.oas.models.servers.ServerVariables import io.swagger.v3.oas.models.tags.Tag import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.ANNOUNCEMENTS import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.API_KEYS @@ -27,7 +34,6 @@ import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.DUP import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.FILE_SYSTEM import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.HISTORY import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.LIBRARIES -import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.LOGIN import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.MIHON import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.OAUTH2 import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.READLISTS @@ -41,6 +47,7 @@ import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.SER import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.SYNCPOINTS import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.TASKS import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.USERS +import org.gotson.komga.infrastructure.swagger.OpenApiConfiguration.TagNames.USER_SESSION import org.springframework.beans.factory.annotation.Value import org.springframework.context.annotation.Bean import org.springframework.context.annotation.Configuration @@ -60,13 +67,13 @@ class OpenApiConfiguration( """ Komga RESTful API. - # Authentication + ## Authentication Most endpoints require authentication. Authentication is done using either: - Basic Authentication - Passing an API Key in the `X-API-Key` header - # Sessions + ## Sessions Upon successful authentication, a session is created, and can be reused. @@ -75,15 +82,15 @@ class OpenApiConfiguration( If you need to set the session cookie later on, you can call `/api/v1/login/set-cookie` with `X-Auth-Token`. The response will contain the `Set-Cookie` header. - # Remember Me + ## Remember Me During authentication, if a request parameter `remember-me` is passed and set to `true`, the server will also return a `remember-me` cookie. This cookie will be used to login automatically even if the session has expired. - # Logout + ## Logout You can explicitly logout an existing session by calling `/api/logout`. This would return a `204`. - # Deprecation + ## Deprecation API endpoints marked as deprecated will be removed in the next major version. """.trimIndent(), @@ -108,6 +115,38 @@ class OpenApiConfiguration( ), ).tags(tags) .extensions(mapOf("x-tagGroups" to tagGroups)) + .servers( + listOf( + Server() + .url("http://localhost:{port}") + .description("Local development server") + .variables( + ServerVariables() + .addServerVariable( + "port", + ServerVariable() + .addEnumItem("8080") + .addEnumItem("25600"), + ), + ), + Server() + .url("https://demo.komga.org") + .description("Demo server"), + ), + ).path( + "/api/logout", + PathItem() + .summary("Logout current session") + .get(logoutOperation.operationId("getLogout")) + .post(logoutOperation.operationId("postLogout")), + ) + + private val logoutOperation = + Operation() + .tags(listOf(USER_SESSION)) + .summary("Logout") + .description("Invalidates the current session and clean up any remember-me authentication.") + .responses(ApiResponses().addApiResponse("204", ApiResponse().description("No Content"))) data class TagGroup( val name: String, @@ -169,7 +208,7 @@ class OpenApiConfiguration( CURRENT_USER, USERS, API_KEYS, - LOGIN, + USER_SESSION, OAUTH2, SYNCPOINTS, ), @@ -229,7 +268,7 @@ class OpenApiConfiguration( const val CURRENT_USER = "Current user" const val USERS = "Users" const val API_KEYS = "API Keys" - const val LOGIN = "User login" + const val USER_SESSION = "User session" const val OAUTH2 = "OAuth2" const val SYNCPOINTS = "Sync points" @@ -270,7 +309,7 @@ class OpenApiConfiguration( Tag().name(CURRENT_USER).description("Manage current user."), Tag().name(USERS).description("Manage users."), Tag().name(API_KEYS).description("Manage API Keys"), - Tag().name(LOGIN), + Tag().name(USER_SESSION), Tag().name(OAUTH2).description("List registered OAuth2 providers"), Tag().name(SYNCPOINTS).description("Sync points are automatically created during a Kobo sync."), Tag().name(CLAIM).description("Claim a freshly installed Komga server."), diff --git a/komga/src/main/kotlin/org/gotson/komga/interfaces/api/rest/LoginController.kt b/komga/src/main/kotlin/org/gotson/komga/interfaces/api/rest/LoginController.kt index ea9587cc..28b84e15 100644 --- a/komga/src/main/kotlin/org/gotson/komga/interfaces/api/rest/LoginController.kt +++ b/komga/src/main/kotlin/org/gotson/komga/interfaces/api/rest/LoginController.kt @@ -16,7 +16,7 @@ import org.springframework.web.bind.annotation.RestController @RestController @RequestMapping(produces = [MediaType.APPLICATION_JSON_VALUE]) -@Tag(name = OpenApiConfiguration.TagNames.LOGIN) +@Tag(name = OpenApiConfiguration.TagNames.USER_SESSION) class LoginController( private val cookieSerializer: CookieSerializer, ) {