refactor(swagger): remove redundant annotations

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")

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

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<Long>?,
     @RequestParam(name = "media_status", required = false) mediaStatus: List<Media.Status>?,
-    @Parameter(hidden = true) page: Pageable
+    @ParameterObject page: Pageable
   ): Page<BookDto> {
     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<ByteArray> =
     bookRepository.findByIdOrNull((bookId))?.let { book ->

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<Long>?,
     @RequestParam(name = "status", required = false) metadataStatus: List<SeriesMetadata.Status>?,
-    @Parameter(hidden = true) page: Pageable
+    @ParameterObject page: Pageable
   ): Page<SeriesDto> {
     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<Media.Status>?,
-    @Parameter(hidden = true) page: Pageable
+    @ParameterObject page: Pageable
   ): Page<BookDto> {
     seriesRepository.findByIdOrNull(id)?.let {
       if (!principal.user.canAccessSeries(it)) throw ResponseStatusException(HttpStatus.UNAUTHORIZED)