Build A Doc2FAQ App: Project Setup Guide
Hey guys! Ready to kick off the Doc2FAQ app? Awesome! This guide will walk you through setting up the initial project structure using Spring Boot, so you'll have a solid foundation to build upon. We'll cover everything from project creation to ensuring your application runs smoothly. Let's get started and make sure that we have a good foundation!
Creating Your Spring Boot Project
Alright, first things first: we need a project! You have a couple of choices here, guys: Maven or Gradle. Both are solid build tools, but I will be using Maven. If you're using IntelliJ IDEA, you can use its built-in project creation wizard. It's super helpful. Open IntelliJ, and select 'New Project'. Make sure you select the Spring Initializr option on the left side, then set the following options:
- Project SDK: Choose your installed JDK version.
- Type: Maven Project.
- Language: Java. (Or Kotlin if you are feeling a bit adventurous)
- Group: Something like 'com.example'.
- Artifact: 'doc2faq-app' (or whatever you prefer).
- Version: The default one usually works.
- Package: The same as the Group ID.
- Dependencies: Select 'Spring Web'. This will include all the necessary dependencies to create a web application. Also, select Spring Boot DevTools. This tool will help you auto-reload your application when you make changes.
Click 'Next'. On the next screen, you can review the settings and then click 'Finish'. IntelliJ will download all the dependencies for you. Now, let's create a basic pom.xml file. It's the heart of your Maven project, and it should look something like this. After you create the pom.xml, run mvn clean install to ensure everything is set up. You can find this in the IntelliJ terminal. The build should be successful, and then you are ready for the next step.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>doc2faq-app</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.0.0</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
Setting up the Basic Project Structure
With the project created, let's establish a clear structure for our code. Your project directory should look something like this:
doc2faq-app/
│
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/
│ │ │ └── example/
│ │ │ └── doc2faqapp/
│ │ │ └── Doc2faqAppApplication.java
│ │ ├── resources/
│ │ │ ├── application.properties
│ │ │ └── static/
│ │ │ └── index.html
│ │ └── test/
│ │ └── java/
│ │ └── com/
│ │ └── example/
│ │ └── doc2faqapp/
│ │ └── Doc2faqAppApplicationTests.java
│
├── pom.xml
└── README.md
src/main/java: This is where all your Java source code lives. You'll find a package structure based on your group ID (e.g.,com.example.doc2faqapp). The main application class (Doc2faqAppApplication.java) will be here. This is also where you'll create controllers, services, and other components later on.src/main/resources: This folder holds your application resources, such as properties files, static content (HTML, CSS, JavaScript), and templates.src/test/java: Test files for your code go here. We'll set up some basic tests later.pom.xml: The Maven project file, which we've already started working on.README.md: A file to document your project (more on that later).
Let's go into src/main/java/com/example/doc2faqapp/Doc2faqAppApplication.java and modify it. This is your main application class, which Spring Boot uses to bootstrap the application. By default, it looks like this:
package com.example.doc2faqapp;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Doc2faqAppApplication {
public static void main(String[] args) {
SpringApplication.run(Doc2faqAppApplication.class, args);
}
}
This class is annotated with @SpringBootApplication, which combines @Configuration, @EnableAutoConfiguration, and @ComponentScan. This means Spring Boot will automatically configure and scan for components. Now, you should modify the application file and add your first controller.
package com.example.doc2faqapp;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@SpringBootApplication
@Controller
public class Doc2faqAppApplication {
public static void main(String[] args) {
SpringApplication.run(Doc2faqAppApplication.class, args);
}
@GetMapping("/")
public String index(Model model) {
model.addAttribute("message", "Hello, Doc2FAQ App!");
return "index"; // This will map to src/main/resources/templates/index.html
}
}
Now, let's create the index.html file in the src/main/resources/templates directory. It should contain a simple HTML structure.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Doc2FAQ App</title>
</head>
<body>
<h1>Welcome to the Doc2FAQ App</h1>
<p th:text="${message}">This is a placeholder message.</p>
</body>
</html>
Creating a Landing Page
Now, let's create a basic landing page. This will be the first thing your users see when they access your application. We'll create a simple HTML page that displays a welcome message and a brief description of the Doc2FAQ app. You can put this in the src/main/resources/static directory. Create a file called index.html and add the following content. This HTML file will serve as our welcome screen. Make sure that you understand the structure of the HTML, otherwise, it will not render correctly.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Doc2FAQ App</title>
</head>
<body>
<h1>Welcome to the Doc2FAQ App</h1>
<p>This is a starting point for the Doc2FAQ application. It is designed to automatically generate FAQs from your documentation.</p>
</body>
</html>
This is a super basic HTML file. It has a title, and a welcome message. Later on, you can make this landing page fancy with CSS and JavaScript, but for now, this works great. Now, the next step is to make sure your Spring Boot application knows how to serve this page. You need to create a controller to handle the incoming requests.
package com.example.doc2faqapp;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class IndexController {
@GetMapping("/")
public String index(Model model) {
model.addAttribute("message", "Welcome to the Doc2FAQ App!");
return "index"; // This will look for index.html in the templates directory.
}
}
Make sure that your application loads and that you can access the landing page by going to http://localhost:8080/ in your browser.
Setting up a .gitignore File
To keep your project clean and avoid accidentally committing unnecessary files, it's super important to set up a .gitignore file. This file tells Git which files and folders to ignore when tracking changes. Here's a basic .gitignore file for a Spring Boot project:
# IntelliJ IDEA
.idea/
# Maven
target/
# OS generated files
.DS_Store
# IDE specific files
*.iml
- .idea/: This directory contains IntelliJ IDEA project-specific settings.
- target/: Maven creates the target directory to store the compiled classes and packaged files.
- .DS_Store: This is a macOS-specific file that stores custom folder view settings.
- *.iml: IntelliJ IDEA module files.
Put this file in the root of your project directory. This ensures that these files will not be tracked by Git, and your repository will stay clean and focused on your source code. You can always add other files you want to be ignored, such as log files or temporary files.
Verify the Application Builds and Starts Successfully
Now, let's make sure our application builds and runs without any issues. Open your terminal or the IntelliJ terminal and navigate to your project directory. Run the following command. The command ensures that your project is built correctly. This is part of the Maven lifecycle, and it will compile your code, run tests, and package your application.
mvn clean install
If everything goes well, you should see a