improved examples with annotations

Author: philsturgeon

README.md

@@ -23,6 +23,10 @@ npx bump-cli preview http://localhost:8080/openapi
 
 Want to see how it will look without downloading anything? Take a look at this documentation [deployed with Bump.sh](https://bump.sh/bump-examples/hub/code-samples/doc/spring-code-first) already.
 
+## Thanks 
+
+The sample code was inspired by https://github.com/spring-guides/tut-rest
+
 ## License
 
 The contents of this repository are licensed under [CC BY-NC-SA

pom.xml

@@ -35,11 +35,27 @@
 			<artifactId>spring-boot-starter-web</artifactId>
 		</dependency>
 
-		<dependency>
+    <!-- This is all you need to add for OpenAPI -->
+    <dependency>
 			<groupId>org.springdoc</groupId>
 			<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
 			<version>2.8.8</version>
 		</dependency>
+    <!-- /end -->
+
+    <!-- some handy stuff you dont need for OpenAPI -->
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-data-jpa</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>com.h2database</groupId>
+			<artifactId>h2</artifactId>
+			<scope>runtime</scope>
+		</dependency>
+    <!-- /end -->
+
 	</dependencies>
 
 	<build>

src/main/java/com/bumpsh/demo/Employee.java

@@ -0,0 +1,81 @@
+package com.bumpsh.demo;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.Id;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Entity
+@Schema(description = "Employees are individuals who work for an organization, " +
+  "contributing their skills and expertise to achieve the organization's goals." +
+
+  "Roles are the specific functions or positions that employees occupy within the organization, " +
+  "defining their duties, responsibilities, and the scope of their work."
+)
+class Employee {
+
+	private @Id
+
+  @Schema(accessMode = Schema.AccessMode.READ_ONLY, description = "Unique identifier which should not be shared publicly", example = "1234")
+	@GeneratedValue Long id;
+	
+  @Schema(description = "Employee name", example = "Bilbo Baggins")
+  private String name;
+
+  @Schema(description = "Employee role", example = "Software Engineer")
+	private String role;
+
+	Employee() {}
+
+	Employee(String name, String role) {
+		this.name = name;
+		this.role = role;
+	}
+
+	public Long getId() {
+		return this.id;
+	}
+
+	public String getName() {
+		return this.name;
+	}
+
+	public String getRole() {
+		return this.role;
+	}
+
+	public void setId(Long id) {
+		this.id = id;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+
+	public void setRole(String role) {
+		this.role = role;
+	}
+
+	// @Override
+	// public boolean equals(Object o) {
+
+	// 	if (this == o)
+	// 		return true;
+	// 	if (!(o instanceof Employee))
+	// 		return false;
+	// 	Employee employee = (Employee) o;
+	// 	return Objects.equals(this.id, employee.id) && Objects.equals(this.name, employee.name)
+	// 			&& Objects.equals(this.role, employee.role);
+	// }
+
+	// @Override
+	// public int hashCode() {
+	// 	return Objects.hash(this.id, this.name, this.role);
+	// }
+
+	// @Override
+	// public String toString() {
+	// 	return "Employee{" + "id=" + this.id + ", name='" + this.name + '\'' + ", role='" + this.role + '\'' + '}';
+	// }
+}

src/main/java/com/bumpsh/demo/EmployeeController.java

@@ -0,0 +1,79 @@
+package com.bumpsh.demo;
+
+import java.util.List;
+
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Parameter;
+
+@RestController
+@Tag(name = "Employee Management", description = "Operations related to employee management")
+class EmployeeController {
+
+	private final EmployeeRepository repository;
+
+	EmployeeController(EmployeeRepository repository) {
+		this.repository = repository;
+	}
+
+	// Aggregate root
+	@GetMapping("/employees")
+  @Operation(summary = "Get all employees", description = "Returns a list of all employees")
+	List<Employee> all() {
+		return repository.findAll();
+	}
+
+	@PostMapping("/employees")
+  @Operation(summary = "Create a new employee", description = "Adds a new employee to the system")
+	Employee newEmployee(@RequestBody Employee newEmployee) {
+		return repository.save(newEmployee);
+	}
+	
+	@GetMapping("/employees/{id}")
+  @Operation(summary = "Get an employee by ID", description = "Returns the details of an employee based on the provided ID")
+  @ApiResponse(
+    responseCode = "200", 
+    description = "Successful operation", 
+    content = @Content(mediaType = "application/json", 
+    schema = @Schema(implementation = Employee.class))
+  )
+	public Employee one(
+      @Parameter(in = ParameterIn.PATH, description = "ID of the employee to retrieve", required = true, schema = @Schema(type = "integer")) 
+      @PathVariable Long id) {
+    return repository.findById(id)
+        .orElseThrow(() -> new EmployeeNotFoundException(id));
+  }
+
+	@PutMapping("/employees/{id}")
+  @Operation(summary = "Update an existing employee", description = "Updates the details of an employee based on the provided ID")
+	Employee replaceEmployee(@RequestBody Employee newEmployee, @PathVariable Long id) {
+		return repository.findById(id)
+			.map(employee -> {
+				employee.setName(newEmployee.getName());
+				employee.setRole(newEmployee.getRole());
+				return repository.save(employee);
+			})
+			.orElseGet(() -> {
+				return repository.save(newEmployee);
+			});
+	}
+
+	@DeleteMapping("/employees/{id}")
+  @Operation(summary = "Delete an employee", description = "Removes an employee from the system based on the provided ID")
+	void deleteEmployee(@PathVariable Long id) {
+		repository.deleteById(id);
+	}
+}

src/main/java/com/bumpsh/demo/EmployeeNotFoundAdvice.java

@@ -0,0 +1,16 @@
+package com.bumpsh.demo;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@RestControllerAdvice
+class EmployeeNotFoundAdvice {
+
+	@ExceptionHandler(EmployeeNotFoundException.class)
+	@ResponseStatus(HttpStatus.NOT_FOUND)
+	String employeeNotFoundHandler(EmployeeNotFoundException ex) {
+		return ex.getMessage();
+	}
+}

src/main/java/com/bumpsh/demo/EmployeeNotFoundException.java

@@ -0,0 +1,8 @@
+package com.bumpsh.demo;
+
+class EmployeeNotFoundException extends RuntimeException {
+
+	EmployeeNotFoundException(Long id) {
+		super("Could not find employee " + id);
+	}
+}

src/main/java/com/bumpsh/demo/EmployeeRepository.java

@@ -0,0 +1,7 @@
+package com.bumpsh.demo;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+interface EmployeeRepository extends JpaRepository<Employee, Long> {
+
+}

src/main/java/com/bumpsh/demo/Greeting.java

@@ -0,0 +1,22 @@
+package com.bumpsh.demo;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+class LoadDatabase {
+
+	private static final Logger log = LoggerFactory.getLogger(LoadDatabase.class);
+
+	@Bean
+	CommandLineRunner initDatabase(EmployeeRepository repository) {
+
+		return args -> {
+			log.info("Preloading " + repository.save(new Employee("Bilbo Baggins", "burglar")));
+			log.info("Preloading " + repository.save(new Employee("Frodo Baggins", "thief")));
+		};
+	}
+}