From 29cbc2915dc16a37e4391a4f759366e6f82785fd Mon Sep 17 00:00:00 2001 From: Sampada <46674082+sampada07@users.noreply.github.com> Date: Sun, 24 May 2020 23:25:06 +0530 Subject: [PATCH] BAEL-3609: Improve article Documenting a Spring REST API Using OpenAPI (#9334) 3.0 --- .../spring-boot-springdoc/pom.xml | 52 +++++++++++++++++++ .../springdoc/controller/BookController.java | 16 +++++- .../java/com/baeldung/springdoc/kotlin/Foo.kt | 17 ++++++ .../springdoc/kotlin/FooController.kt | 30 +++++++++++ .../src/main/resources/application.properties | 1 + 5 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/Foo.kt create mode 100644 spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/FooController.kt diff --git a/spring-boot-modules/spring-boot-springdoc/pom.xml b/spring-boot-modules/spring-boot-springdoc/pom.xml index 1c1f27b5a5..4bede8c796 100644 --- a/spring-boot-modules/spring-boot-springdoc/pom.xml +++ b/spring-boot-modules/spring-boot-springdoc/pom.xml @@ -66,6 +66,22 @@ spring-restdocs-restassured test + + + + org.springdoc + springdoc-openapi-kotlin + ${springdoc.version} + + + org.jetbrains.kotlin + kotlin-stdlib-jre8 + ${kotlin.version} + + + org.jetbrains.kotlin + kotlin-reflect + @@ -97,6 +113,41 @@ + + + kotlin-maven-plugin + org.jetbrains.kotlin + ${kotlin.version} + + + spring + + ${java.version} + + + + compile + compile + + compile + + + + test-compile + test-compile + + test-compile + + + + + + org.jetbrains.kotlin + kotlin-maven-allopen + ${kotlin.version} + + + @@ -116,6 +167,7 @@ 5.2.10.Final 1.2.32 1.5.6 + 1.2.71 ${project.build.directory}/generated-snippets diff --git a/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/controller/BookController.java b/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/controller/BookController.java index 05f8c5a946..326a97149b 100644 --- a/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/controller/BookController.java +++ b/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/controller/BookController.java @@ -25,6 +25,13 @@ import com.baeldung.springdoc.exception.BookNotFoundException; import com.baeldung.springdoc.model.Book; import com.baeldung.springdoc.repository.BookRepository; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + @RestController @RequestMapping("/api/book") public class BookController { @@ -32,8 +39,15 @@ public class BookController { @Autowired private BookRepository repository; + // @formatter:off + @Operation(summary = "Get a book by its id") + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "Found the book", + content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Book.class)) }), + @ApiResponse(responseCode = "400", description = "Invalid id supplied", content = @Content), + @ApiResponse(responseCode = "404", description = "Book not found", content = @Content) }) // @formatter:on @GetMapping("/{id}") - public Book findById(@PathVariable long id) { + public Book findById(@Parameter(description = "id of book to be searched") @PathVariable long id) { return repository.findById(id) .orElseThrow(() -> new BookNotFoundException()); } diff --git a/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/Foo.kt b/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/Foo.kt new file mode 100644 index 0000000000..3bc3c8fe61 --- /dev/null +++ b/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/Foo.kt @@ -0,0 +1,17 @@ +package com.baeldung.springdoc.kotlin + +import javax.persistence.Entity +import javax.persistence.GeneratedValue +import javax.persistence.Id +import javax.validation.constraints.NotBlank +import javax.validation.constraints.Size + +@Entity +data class Foo( + @Id + val id: Long = 0, + + @NotBlank + @Size(min = 0, max = 50) + val name: String = "" +) \ No newline at end of file diff --git a/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/FooController.kt b/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/FooController.kt new file mode 100644 index 0000000000..d3ecd6a6ba --- /dev/null +++ b/spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/springdoc/kotlin/FooController.kt @@ -0,0 +1,30 @@ +package com.baeldung.springdoc.kotlin + +import io.swagger.v3.oas.annotations.Operation +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 +import io.swagger.v3.oas.annotations.responses.ApiResponses +import org.springframework.web.bind.annotation.GetMapping +import org.springframework.web.bind.annotation.RequestMapping +import org.springframework.web.bind.annotation.RestController + +@RestController +@RequestMapping("/") +class FooController() { + val fooList: List = listOf(Foo(1, "one"), Foo(2, "two")) + + @Operation(summary = "Get all foos") + @ApiResponses(value = [ + ApiResponse(responseCode = "200", description = "Found Foos", content = [ + (Content(mediaType = "application/json", array = ( + ArraySchema(schema = Schema(implementation = Foo::class)))))]), + ApiResponse(responseCode = "400", description = "Bad request", content = [Content()]), + ApiResponse(responseCode = "404", description = "Did not find any Foos", content = [Content()])] + ) + @GetMapping("/foo") + fun getAllFoos(): List = fooList +} + + diff --git a/spring-boot-modules/spring-boot-springdoc/src/main/resources/application.properties b/spring-boot-modules/spring-boot-springdoc/src/main/resources/application.properties index 7debdc6503..0eecfbb1c4 100644 --- a/spring-boot-modules/spring-boot-springdoc/src/main/resources/application.properties +++ b/spring-boot-modules/spring-boot-springdoc/src/main/resources/application.properties @@ -1,5 +1,6 @@ # custom path for swagger-ui springdoc.swagger-ui.path=/swagger-ui-custom.html +springdoc.swagger-ui.operationsSorter=method # custom path for api docs springdoc.api-docs.path=/api-docs