{"id":22191645,"url":"https://github.com/leosimoes/templatecode-java-spring-restapi","last_synced_at":"2026-05-17T02:36:46.845Z","repository":{"id":234545202,"uuid":"789113998","full_name":"leosimoes/TemplateCode-Java-Spring-RestAPI","owner":"leosimoes","description":"Template Code for a Rest API in the Java language with Spring Framework and Gradle.","archived":false,"fork":false,"pushed_at":"2024-04-23T16:09:02.000Z","size":1724,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-30T01:16:36.437Z","etag":null,"topics":["java","rest-api","spring"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leosimoes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-04-19T18:17:18.000Z","updated_at":"2024-04-23T16:09:06.000Z","dependencies_parsed_at":"2024-04-19T19:33:29.851Z","dependency_job_id":"83b686e2-ecc6-4d9d-bb41-112b380dafc6","html_url":"https://github.com/leosimoes/TemplateCode-Java-Spring-RestAPI","commit_stats":null,"previous_names":["leosimoes/templatecode-java-spring-restapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leosimoes%2FTemplateCode-Java-Spring-RestAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leosimoes%2FTemplateCode-Java-Spring-RestAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leosimoes%2FTemplateCode-Java-Spring-RestAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leosimoes%2FTemplateCode-Java-Spring-RestAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leosimoes","download_url":"https://codeload.github.com/leosimoes/TemplateCode-Java-Spring-RestAPI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245351757,"owners_count":20601088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","rest-api","spring"],"created_at":"2024-12-02T12:17:04.344Z","updated_at":"2026-05-17T02:36:46.817Z","avatar_url":"https://github.com/leosimoes.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TemplateCode - Java - Spring - Rest API\nAuthor: Leonardo Simões\n\nTemplate Code for a Rest API in the Java language with Spring Framework and Gradle.\nThe API has two resources: MainResource and AssociatedResource.\n\n\n## Development steps\nThe project development steps were:\n\n1. Create project (in IntelliJ) with:\n- Java language (17);\n- Spring Framework (6.2.3);\n- Dependencies: Web, DevTools, Lombok, JPA, H2 and Validation.\n\n![Image-01-IntelliJ](images/Image-01-IntelliJ.png)\n\n2. Change the start of the Run screen with custom text (or image):\n- format the desired text using `https://springhow.com/spring-boot-banner-generator/` and download `banner.txt`;\n\n![Image-02-BannerGenerator](images/Image-02-BannerGenerator.png)\n\n- place the `banner.txt` file in `src/main/resources` (or another path);\n- (optional) add `${spring.application.name}` and `Spring Boot ${spring-boot.formatted-version}` in `banner.txt`;\n- (optional) configure the `banner.txt` file path in `application.properties`:\n    * `spring.banner.location=classpath:/banner.txt`.\n\n3. Configure the H2 database:\n- In `build.gradle` configure according to the desired type of use:\n* `implementation 'com.h2database:h2'`;\n* `runtimeOnly 'com.h2database:h2'`;\n* `testImplementation 'com.h2database:h2'`;\n- In `application.properties`:\n\n```properties\n# ======================================================\n#               APPLICATION\n# ======================================================\nspring.application.name=TemplateCode-Java-Spring-RestAPI\n# spring.banner.location=classpath:/banner.txt\n# ======================================================\n#               DATASOURCE - H2 DATABASE\n# ======================================================\nspring.datasource.url=jdbc:h2:mem:proddb\nspring.datasource.driver-class-name=org.h2.Driver\nspring.datasource.username=leo\nspring.datasource.password=senha\nspring.h2.console.enabled=true\nspring.h2.console.path=/h2\n```\n\n![Image-03-Terminal-Run](images/Image-03-Terminal-Run.png)\n\n- test access to the H2 console at `http://localhost:8080/h2/`:\n\n![Image-04-B-ConsoleH2](images/Image-04-B-ConsoleH2.png)\n\nNote:\n- By default, the usename would be \"sa\" and the password \"\", and the h2 console would be disabled.\n\n4. Create AssociatedEntity class:\n- in the `entities` package;\n- with attributes UUID id, String name;\n- corresponding to the table named `ASSOCIATEDS`.\n\n5. Create MainEntity class:\n- in the `entities` package;\n- with UUID id, String name, String description and AssociatedEntity associated attributes;\n- corresponding to the table named `MAINS`.\n\n![Image-05-UML-Classes-Entities](images/Image-05-UML-Classes-Entities.png)\n\nNote: When creating classes that represent database entities:\n- annotate them with `@Entity`, `@Table(name=\"...\")` to map entity;\n- annotate them with `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor` to use Lombok;\n- add attribute `UUID id` annotated with `@Id` and `@GeneratedValue(strategy = GenerationType.UUID)`;\n- configure relationships with `@ManyToOne`, `@OneToMany` or `@OneToOne` in attributes that are objects;\n- configure the other columns with `@Column` and perhaps some validator like `@NotBlank` or `@NotNull`;\n- log into the H2 console and check if the tables were created correctly:\n\n![Image-06-ConsoleH2-Tables](images/Image-06-ConsoleH2-Tables.png)\n\n6. Create tables from SQL script (not from Hibernate):\n- run the application with `spring.jpa.hibernate.ddl-auto=create-drop` in `application.properties`;\n- execute the command `SCRIPT` or (`SCRIPT TO 'D:/schema.sql'`) to obtain SQL code for creating tables;\n- place the content of the previous step in `src/main/resources/schema.sql`;\n- run the application with `spring.jpa.hibernate.ddl-auto=none` and\n  `spring.jpa.defer-datasource-initialization=true` in `application.properties`;\n\n```properties\n# spring.jpa.hibernate.ddl-auto=create-drop\nspring.jpa.hibernate.ddl-auto=none\nspring.jpa.defer-datasource-initialization=true\nspring.sql.init.mode=always\n```\n\n- (optional) configure the `schema.sql` file path in `application.properties`:\n  * `spring.sql.init.schema-locations=classpath:/schema.sql`.\n\n![Image-07-ConsoleH2-BackupSQL](images/Image-07-ConsoleH2-BackupSQL.png)\n\n7. Create `AssociatedRepository` and `MainRepository` interfaces:\n- in the `repositories` package;\n- annotated with `@Repository`;\n- extends `JPARepository`;\n- have declaration of the methods `Boolean existsByNameEqualsIgnoreCase(String name)` and\n  `Optional\u003cMainEntity\u003e findByNameEqualsIgnoreCase(String name);`.\n\n![Image-08-UML-Interfaces-Repositories](images/Image-08-UML-Interfaces-Repositories.png)\n\n8. Create dtos classes `AssociatedPayload` and `MainPayload`:\n- in the `dtos` package;\n- annotated with `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor` to use Lombok;\n\n![Image-09-UML-Classes-DTOs](images/Image-09-UML-Classes-DTOs.png)\n\n9. Create mappers between dtos classes (\"payloads\") and entities classes (\"entities\"):\n- add addons in `build.gradle`:\n\n```groovy\n// compileOnly 'org.projectlombok:lombok'\nimplementation 'org.projectlombok:lombok'\nimplementation 'org.mapstruct:mapstruct:1.5.5.Final'\nannotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'\ntestAnnotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'\nimplementation 'org.projectlombok:lombok-mapstruct-binding:0.2.0'\n```\n\n- create the `AssociatedMapper` and `MainMapper` interfaces:\n  * in the `mappers` package;\n  * annotated with `@Mapper`;\n  * with `INSTANCE` attribute;\n  * with 4 methods for conversions between entity and payload, and between list of entities and list of payloads;\n  * `MainMapper` has two helper methods:\n    * `default AssociatedEntity toAssociated(MainPayload payload)`;\n    * `default String map(AssociatedEntity associatedEntity)`;\n\n![Image-10-UML-Interfaces-Mappers](images/Image-10-UML-Interfaces-Mappers.png)\n\n10. Create Services layer:\n- in the `services` package;\n- add `MainService` and `AssociatedService` interfaces;\n- add `MainServiceImpl` and `AssociatedServiceImpl` classes:\n  * annotated with `@Service`;\n  * implement the interfaces;\n  * have the mapper and repository(ies) of the entity(ies);\n  * have a constructor with all attributes and annotated with `@Autowired`;\n- the methods must be `create`, `getByName`, `getAll`, `update` and `deleteByName`;\n\n![Image-11-UML-Services](images/Image-11-UML-Services.png)\n\n11. Create Controllers layer:\n- in the `controllers` package;\n- add `MainController` and `AssociatedController` classes:\n  * annotated with `@RestController` and `@RequestMapping(\"api/v1/...\")`;\n  * have a constructor with an attribute and annotated with `@Autowired`;\n  * methods must be `create`, `getByName`, `getAll`, `update` and `deleteByName`.\n\n![Image-12-UML-Controllers](images/Image-12-UML-Controllers.png)\n\n12. Create Exceptions:\n- in the `exceptions` package;\n- with names `AssociatedNotFoundException`, `MainNotFoundException` and `AssociatedNameAlreadyRegisteredException`\n  `MainNameAlreadyRegisteredException`;\n- inherit from `RuntimeException`;\n- have a constructor with argument `String message` and another with `String message, Throwable cause` as arguments;\n- use them instead of `RunTimeException` in Services implementations.\n\n13. Create `ResourcesControllerAdvice` class:\n- in the `exceptions` package;\n- annotated with `@RestControllerAdvice`;\n- the methods:\n  * annotated with `@ExceptionHandler`, and receives some exception;\n  * has names starting with \"handle\";\n  * return `ResponseEntity\u003cString\u003e`.\n\n![Image-13-UML-Classes-Exceptions](images/Image-13-UML-Classes-Exceptions.png)\n\n\n## References\nSpring - Guides - Tutorials - Building REST services with Spring:\nhttps://spring.io/guides/tutorials/rest\n\nBaeldung - Rest with Spring Series:\nhttps://www.baeldung.com/rest-with-spring-series\n\nBaeldung - Spring Boot With H2 Database:\nhttps://www.baeldung.com/spring-boot-h2-database\n\nBaeldung - Quick Guide on Loading Initial Data with Spring Boot:\nhttps://www.baeldung.com/spring-boot-data-sql-and-schema-sql\n\nDZone - That’s How You Can Use MapStruct With Lombok in Your Spring Boot Application:\nhttps://dzone.com/articles/thats-why-you-need-to-use-mapstruct-in-your-spring","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleosimoes%2Ftemplatecode-java-spring-restapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleosimoes%2Ftemplatecode-java-spring-restapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleosimoes%2Ftemplatecode-java-spring-restapi/lists"}