BAEL-3609: Improve article Documenting a Spring REST API Using OpenAPI (#9334)

3.0

spring-boot-modules/spring-boot-springdoc/pom.xml

@@ -66,6 +66,22 @@
             <artifactId>spring-restdocs-restassured</artifactId>
             <scope>test</scope>
         </dependency> 
+        
+        <!--kotlin dependencies -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-kotlin</artifactId>
+            <version>${springdoc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.jetbrains.kotlin</groupId>
+            <artifactId>kotlin-stdlib-jre8</artifactId>
+            <version>${kotlin.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.jetbrains.kotlin</groupId>
+            <artifactId>kotlin-reflect</artifactId>
+        </dependency>
     </dependencies>
 
     <build>
@@ -97,6 +113,41 @@
                     </execution>
                 </executions>
             </plugin>
+        <!-- kotlin -->
+         <plugin>
+                <artifactId>kotlin-maven-plugin</artifactId>
+                <groupId>org.jetbrains.kotlin</groupId>
+                <version>${kotlin.version}</version>
+                <configuration>
+                    <compilerPlugins>
+                        <plugin>spring</plugin>
+                    </compilerPlugins>
+                    <jvmTarget>${java.version}</jvmTarget>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>compile</id>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>compile</goal>
+                        </goals>
+                    </execution>
+                    <execution>
+                        <id>test-compile</id>
+                        <phase>test-compile</phase>
+                        <goals>
+                            <goal>test-compile</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.jetbrains.kotlin</groupId>
+                        <artifactId>kotlin-maven-allopen</artifactId>
+                        <version>${kotlin.version}</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
         </plugins>
         <resources>
             <resource>
@@ -116,6 +167,7 @@
         <hibernate.version>5.2.10.Final</hibernate.version>
         <springdoc.version>1.2.32</springdoc.version>
         <asciidoctor-plugin.version>1.5.6</asciidoctor-plugin.version>
+        <kotlin.version>1.2.71</kotlin.version>
         <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
     </properties>
 

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());
     }

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

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<Foo> = 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<Foo> = fooList
+}
+
+

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