Setup swagger

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>conorheffron</groupId>
 	<artifactId>ironoc</artifactId>
-	<version>4.2.0</version>
+	<version>4.3.0</version>
 	<packaging>war</packaging>
 
 	<distributionManagement>
@@ -34,6 +34,7 @@
 	</properties>
 
 	<dependencies>
+		<!-- Spring -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot</artifactId>
@@ -50,7 +51,6 @@
 				</exclusion>
 			</exclusions>
 		</dependency>
-
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-log4j2</artifactId>
@@ -67,6 +67,7 @@
 			<version>${spring.version}</version>
 			<scope>provided</scope>
 		</dependency>
+		<!-- Jakarta -->
 		<dependency>
 			<groupId>jakarta.servlet</groupId>
 			<artifactId>jakarta.servlet-api</artifactId>
@@ -87,6 +88,7 @@
 			<artifactId>jakarta.ws.rs-api</artifactId>
 			<version>4.0.0</version>
 		</dependency>
+		<!-- web server -->
 		<dependency>
 			<groupId>org.glassfish.web</groupId>
 			<artifactId>jakarta.servlet.jsp.jstl</artifactId>
@@ -97,6 +99,7 @@
 			<artifactId>tomcat-embed-jasper</artifactId>
 			<version>10.1.28</version>
 		</dependency>
+		<!-- Unit/integration tests -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-test</artifactId>
@@ -115,11 +118,13 @@
 			<version>4.13.2</version>
 			<scope>test</scope>
 		</dependency>
+		<!-- lombok -->
 		<dependency>
 			<groupId>org.projectlombok</groupId>
 			<artifactId>lombok</artifactId>
 			<scope>provided</scope>
 		</dependency>
+		<!-- apache -->
 		<dependency>
 			<groupId>commons-io</groupId>
 			<artifactId>commons-io</artifactId>
@@ -130,6 +135,22 @@
 			<artifactId>commons-lang3</artifactId>
 			<version>3.16.0</version>
 		</dependency>
+		<!-- swagger -->
+		<dependency>
+			<groupId>org.springdoc</groupId>
+			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+			<version>2.6.0</version>
+		</dependency>
+		<dependency>
+			<groupId>io.springfox</groupId>
+			<artifactId>springfox-boot-starter</artifactId>
+			<version>3.0.0</version>
+		</dependency>
+		<dependency>
+			<groupId>org.springdoc</groupId>
+			<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
+			<version>2.6.0</version>
+		</dependency>
 	</dependencies>
 
 	<build>

src/main/java/com/ironoc/portfolio/controller/CustomErrorController.java

@@ -5,11 +5,11 @@
 import jakarta.servlet.http.HttpServletRequest;
 
 import org.springframework.boot.web.servlet.error.ErrorController;
+import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.servlet.view.RedirectView;
 
-@RestController
+@Controller
 public class CustomErrorController extends AbstractLogger implements  ErrorController {
 
     protected static final String PATH = "/error";

src/main/java/com/ironoc/portfolio/controller/GitProjectsController.java

@@ -4,21 +4,24 @@
 import com.ironoc.portfolio.dto.RepositoryDetailDto;
 import com.ironoc.portfolio.logger.AbstractLogger;
 import com.ironoc.portfolio.service.GitDetailsService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import jakarta.servlet.http.HttpServletRequest;
 import org.apache.commons.lang3.StringUtils;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
-import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
 
 import java.util.Collections;
 import java.util.List;
 
-@Controller
+@RestController
 public class GitProjectsController extends AbstractLogger {
 
 	@Autowired
@@ -28,12 +31,24 @@ public GitProjectsController(GitDetailsService gitDetailsService) {
 		this.gitDetailsService = gitDetailsService;
 	}
 
+	@Operation(summary = "Get repository details by GitHub username",
+			description = "Returns a list of Github repository details per username path variable.")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200",
+					description = "Successfully retrieved GitHub projects for username path variable.")
+	})
 	@GetMapping(value = {"/get-repo-detail/{username}/"}, produces= MediaType.APPLICATION_JSON_VALUE)
 	public ResponseEntity<List<RepositoryDetailDomain>> getReposByUsernamePathVar(HttpServletRequest request,
 															  @PathVariable(value = "username") String username) {
 		return getReposByUsername(request, username);
 	}
 
+	@Operation(summary = "Get repository details by GitHub username",
+			description = "Returns a list of Github repository details per 'username' request parameter.")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200",
+					description = "Successfully retrieved GitHub projects for username request parameter.")
+	})
 	@GetMapping(value = {"/get-repo-detail"}, produces= MediaType.APPLICATION_JSON_VALUE)
 	public ResponseEntity<List<RepositoryDetailDomain>> getReposByUsernameReqParam(HttpServletRequest request,
 															  @RequestParam(value = "username") String username) {

src/main/java/com/ironoc/portfolio/domain/RepositoryDetailDomain.java

@@ -1,21 +1,35 @@
 package com.ironoc.portfolio.domain;
 
-import lombok.*;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
 
 @Builder
 @AllArgsConstructor
 @Getter
 public class RepositoryDetailDomain {
 
+    @Schema(name= "name", description = "Name of GitHub Repository.", example = "ironoc-db", required = true)
     private String name;
 
+    @Schema(name= "fullName", description = "Full Name of GitHub Repository (Format is: username/project_name).",
+            example = "conorheffron/ironoc-db", required = true)
     private String fullName;
 
+    @Schema(name= "description", description = "Description of GitHub project.", example = "Personal Portfolio Website.",
+            required = false)
     private String description;
 
+    @Schema(name= "appHome", description = "Normally this value is the link to the project/app home page.",
+            example = "http://ironoc.com", required = false)
     private String appHome;
 
+    @Schema(name = "repoUrl", description = "This is the home page URL of the project.",
+            example = "https://github.com/conorheffron/ironoc-db", required = true)
     private String repoUrl;
 
+    @Schema(name = "topics", description = "Labels or topics associated with the GitHub repository project.",
+            example = "[aws, jdk21, maven, personal, portfolio, spring-boot-3]", required = false)
     private String topics;
 }

src/main/resources/application.yml

@@ -16,4 +16,11 @@ com:
 spring:
   mvc:
     favicon:
-      enabled: false
+      enabled: false
+
+springdoc:
+  api-docs:
+    path: /api-docs
+  swagger-ui:
+    path: /swagger-ui-ironoc.html
+    operationsSorter: method

src/main/webapp/templates/index.html

@@ -39,6 +39,7 @@
                 <li><a href="#about">ABOUT</a></li>
                 <li><a href="#portfolio">PORTFOLIO</a></li>
                 <li><a href="#github-projects">Github Projects</a></li>
+                <li><a target="_blank" href="/swagger-ui-ironoc.html">iRonoc API Doc</a></li>
             </ul>
         </div>
     </div>