diff --git a/komga/build.gradle.kts b/komga/build.gradle.kts index d3fe19b3..4f4cadee 100644 --- a/komga/build.gradle.kts +++ b/komga/build.gradle.kts @@ -51,11 +51,10 @@ dependencies { implementation("io.micrometer:micrometer-registry-influx") run { - val springdocVersion = "1.3.2" + val springdocVersion = "1.3.3" implementation("org.springdoc:springdoc-openapi-ui:$springdocVersion") implementation("org.springdoc:springdoc-openapi-data-rest:$springdocVersion") implementation("org.springdoc:springdoc-openapi-security:$springdocVersion") - implementation("org.springdoc:springdoc-openapi-kotlin:$springdocVersion") } implementation("com.fasterxml.jackson.module:jackson-module-kotlin") diff --git a/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/PageableWithoutSort.kt b/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/PageableWithoutSort.kt new file mode 100644 index 00000000..4318f9f1 --- /dev/null +++ b/komga/src/main/kotlin/org/gotson/komga/infrastructure/swagger/PageableWithoutSort.kt @@ -0,0 +1,13 @@ +package org.gotson.komga.infrastructure.swagger + +import io.swagger.v3.oas.annotations.Parameter +import io.swagger.v3.oas.annotations.Parameters +import io.swagger.v3.oas.annotations.enums.ParameterIn +import io.swagger.v3.oas.annotations.media.Schema + +@Target(AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.FUNCTION) +@Parameters( + Parameter(description = "Zero-based page index (0..N)", `in` = ParameterIn.QUERY, name = "page", schema = Schema(type = "integer", defaultValue = "0")), + Parameter(description = "The size of the page to be returned", `in` = ParameterIn.QUERY, name = "size", schema = Schema(type = "integer", defaultValue = "20")) +) +annotation class PageableWithoutSort diff --git a/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/BookController.kt b/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/BookController.kt index 5b76f89c..81af0ea2 100644 --- a/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/BookController.kt +++ b/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/BookController.kt @@ -5,8 +5,6 @@ import com.github.klinq.jpaspec.likeLower import com.github.klinq.jpaspec.toJoin import io.swagger.v3.oas.annotations.Operation import io.swagger.v3.oas.annotations.Parameter -import io.swagger.v3.oas.annotations.Parameters -import io.swagger.v3.oas.annotations.media.ArraySchema import io.swagger.v3.oas.annotations.media.Content import io.swagger.v3.oas.annotations.media.Schema import io.swagger.v3.oas.annotations.responses.ApiResponse @@ -24,10 +22,12 @@ import org.gotson.komga.domain.model.Series import org.gotson.komga.domain.persistence.BookRepository import org.gotson.komga.infrastructure.image.ImageType import org.gotson.komga.infrastructure.security.KomgaPrincipal +import org.gotson.komga.infrastructure.swagger.PageableWithoutSort import org.gotson.komga.interfaces.rest.dto.BookDto import org.gotson.komga.interfaces.rest.dto.BookMetadataUpdateDto import org.gotson.komga.interfaces.rest.dto.PageDto import org.gotson.komga.interfaces.rest.dto.toDto +import org.springdoc.api.annotations.ParameterObject import org.springframework.core.io.FileSystemResource import org.springframework.data.domain.Page import org.springframework.data.domain.PageRequest @@ -72,21 +72,13 @@ class BookController( private val asyncOrchestrator: AsyncOrchestrator ) { - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")), - Parameter(description = "Sorting criteria in the format: property(,asc|desc). " - + "Default sort order is ascending. " + "Multiple sort criteria are supported." - , name = "sort" - , array = ArraySchema(schema = Schema(type = "string"))) - ) @GetMapping("api/v1/books") fun getAllBooks( @AuthenticationPrincipal principal: KomgaPrincipal, @RequestParam(name = "search", required = false) searchTerm: String?, @RequestParam(name = "library_id", required = false) libraryIds: List?, @RequestParam(name = "media_status", required = false) mediaStatus: List?, - @Parameter(hidden = true) page: Pageable + @ParameterObject page: Pageable ): Page { val pageRequest = PageRequest.of( page.pageNumber, @@ -131,10 +123,7 @@ class BookController( @Operation(description = "Return newly added or updated books.") - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")) - ) + @PageableWithoutSort @GetMapping("api/v1/books/latest") fun getLatestSeries( @AuthenticationPrincipal principal: KomgaPrincipal, @@ -215,10 +204,6 @@ class BookController( } ?: throw ResponseStatusException(HttpStatus.NOT_FOUND) @Operation(description = "Download the book file.") - @ApiResponse(content = [Content( - mediaType = MediaType.APPLICATION_OCTET_STREAM_VALUE, - schema = Schema(type = "string", format = "binary") - )]) @GetMapping(value = [ "api/v1/books/{bookId}/file", "api/v1/books/{bookId}/file/*", @@ -275,7 +260,9 @@ class BookController( request: WebRequest, @PathVariable bookId: Long, @PathVariable pageNumber: Int, + @Parameter(description = "Convert the image to the provided format.", schema = Schema(allowableValues = ["jpeg", "png"])) @RequestParam(value = "convert", required = false) convertTo: String?, + @Parameter(description = "If set to true, pages will start at index 0. If set to false, pages will start at index 1.") @RequestParam(value = "zero_based", defaultValue = "false") zeroBasedIndex: Boolean ): ResponseEntity = bookRepository.findByIdOrNull((bookId))?.let { book -> diff --git a/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/SeriesController.kt b/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/SeriesController.kt index 76cbf54e..3b6cf0df 100644 --- a/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/SeriesController.kt +++ b/komga/src/main/kotlin/org/gotson/komga/interfaces/rest/SeriesController.kt @@ -5,8 +5,6 @@ import com.github.klinq.jpaspec.likeLower import com.github.klinq.jpaspec.toJoin import io.swagger.v3.oas.annotations.Operation import io.swagger.v3.oas.annotations.Parameter -import io.swagger.v3.oas.annotations.Parameters -import io.swagger.v3.oas.annotations.media.ArraySchema import io.swagger.v3.oas.annotations.media.Content import io.swagger.v3.oas.annotations.media.Schema import io.swagger.v3.oas.annotations.responses.ApiResponse @@ -19,10 +17,12 @@ import org.gotson.komga.domain.model.SeriesMetadata import org.gotson.komga.domain.persistence.BookRepository import org.gotson.komga.domain.persistence.SeriesRepository import org.gotson.komga.infrastructure.security.KomgaPrincipal +import org.gotson.komga.infrastructure.swagger.PageableWithoutSort import org.gotson.komga.interfaces.rest.dto.BookDto import org.gotson.komga.interfaces.rest.dto.SeriesDto import org.gotson.komga.interfaces.rest.dto.SeriesMetadataUpdateDto import org.gotson.komga.interfaces.rest.dto.toDto +import org.springdoc.api.annotations.ParameterObject import org.springframework.data.domain.Page import org.springframework.data.domain.PageRequest import org.springframework.data.domain.Pageable @@ -58,21 +58,13 @@ class SeriesController( private val asyncOrchestrator: AsyncOrchestrator ) { - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")), - Parameter(description = "Sorting criteria in the format: property(,asc|desc). " - + "Default sort order is ascending. " + "Multiple sort criteria are supported." - , name = "sort" - , array = ArraySchema(schema = Schema(type = "string"))) - ) @GetMapping fun getAllSeries( @AuthenticationPrincipal principal: KomgaPrincipal, @RequestParam(name = "search", required = false) searchTerm: String?, @RequestParam(name = "library_id", required = false) libraryIds: List?, @RequestParam(name = "status", required = false) metadataStatus: List?, - @Parameter(hidden = true) page: Pageable + @ParameterObject page: Pageable ): Page { val pageRequest = PageRequest.of( page.pageNumber, @@ -116,10 +108,7 @@ class SeriesController( } @Operation(description = "Return recently added or updated series.") - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")) - ) + @PageableWithoutSort @GetMapping("/latest") fun getLatestSeries( @AuthenticationPrincipal principal: KomgaPrincipal, @@ -139,10 +128,7 @@ class SeriesController( } @Operation(description = "Return newly added series.") - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")) - ) + @PageableWithoutSort @GetMapping("/new") fun getNewSeries( @AuthenticationPrincipal principal: KomgaPrincipal, @@ -162,10 +148,7 @@ class SeriesController( } @Operation(description = "Return recently updated series, but not newly added ones.") - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")) - ) + @PageableWithoutSort @GetMapping("/updated") fun getUpdatedSeries( @AuthenticationPrincipal principal: KomgaPrincipal, @@ -208,20 +191,12 @@ class SeriesController( } ?: throw ResponseStatusException(HttpStatus.NOT_FOUND) } ?: throw ResponseStatusException(HttpStatus.NOT_FOUND) - @Parameters( - Parameter(description = "Zero-based page index (0..N)", name = "page", schema = Schema(type = "integer", defaultValue = "0")), - Parameter(description = "The size of the page to be returned", name = "size", schema = Schema(type = "integer", defaultValue = "20")), - Parameter(description = "Sorting criteria in the format: property(,asc|desc). " - + "Default sort order is ascending. " + "Multiple sort criteria are supported." - , name = "sort" - , array = ArraySchema(schema = Schema(type = "string"))) - ) @GetMapping("{seriesId}/books") fun getAllBooksBySeries( @AuthenticationPrincipal principal: KomgaPrincipal, @PathVariable(name = "seriesId") id: Long, @RequestParam(name = "media_status", required = false) mediaStatus: List?, - @Parameter(hidden = true) page: Pageable + @ParameterObject page: Pageable ): Page { seriesRepository.findByIdOrNull(id)?.let { if (!principal.user.canAccessSeries(it)) throw ResponseStatusException(HttpStatus.UNAUTHORIZED)