{"id":26139783,"url":"https://github.com/leanstacks/skeleton-ws-spring-boot","last_synced_at":"2025-04-08T04:16:33.298Z","repository":{"id":26735093,"uuid":"30192698","full_name":"leanstacks/skeleton-ws-spring-boot","owner":"leanstacks","description":"The foundation to start a RESTful web services application using Spring Boot.","archived":false,"fork":false,"pushed_at":"2024-08-02T15:19:08.000Z","size":458,"stargazers_count":118,"open_issues_count":2,"forks_count":109,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-27T14:55:09.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://leanstacks.com/stacks.html#skeleton-boot-ws","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leanstacks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-02T15:12:57.000Z","updated_at":"2025-03-14T13:50:27.000Z","dependencies_parsed_at":"2022-09-01T21:10:26.986Z","dependency_job_id":null,"html_url":"https://github.com/leanstacks/skeleton-ws-spring-boot","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fskeleton-ws-spring-boot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fskeleton-ws-spring-boot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fskeleton-ws-spring-boot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fskeleton-ws-spring-boot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leanstacks","download_url":"https://codeload.github.com/leanstacks/skeleton-ws-spring-boot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773720,"owners_count":20993639,"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":[],"created_at":"2025-03-11T02:37:00.701Z","updated_at":"2025-04-08T04:16:33.277Z","avatar_url":"https://github.com/leanstacks.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Skeleton for Spring Boot Web Services\n\n## Acknowledgements\n\nThis is a [LEAN**STACKS**](http://www.leanstacks.com) solution.\n\nFor more detailed information and instruction about constructing Spring Boot RESTful web services, see the book [Lean Application Engineering Featuring Backbone.Marionette and the Spring Framework](https://leanpub.com/leanstacks-marionette-spring).\n\n## Getting Started\n\nThis is a project skeleton for a [Spring Boot](http://projects.spring.io/spring-boot/) RESTful web services application.\n\n### Features\n\n#### RESTful Web Service Family\nThe project contains examples of **C** reate, **R** ead, **U** pdate, and **D** elete web services.  The project illustrates the use of `@ExceptionHandler` methods and `@ControllerAdvice` classes to manage web service responses when common exceptional conditions arise.\n\n#### Business Services\nThe project demonstrates the encapsulation of business behaviors into domain-specific, Spring-managed services annotated with `@Service`.\n\n#### Spring Data JPA\nThe project shows the use of Spring Data JPA repositories, `@Repository`, for data access and management.  Illustrates the `@Entity` annotation and other JPA entity model annotations for attribute and relationship mapping.\n\n#### HSQLDB In-Memory Database\nThe project illustrates how to use the HSQLDB in-memory database which is useful for rapid prototyping or unit test execution in a continuous integration environment.\n\n#### MySQL Database\nIn addition to HSQLDB support, the project also supports integration with MySQL.\n\n#### Liquibase Database Migration\nThe project demonstrates the use of  [Liquibase](http://www.liquibase.org/) change logs to automatically create and update the database structure and initial content. The Liquibase change logs have been tested with the HSQLDB and MySQL database engines.\n\n#### Transaction Management\nThe project contains examples of the `@Transactional` annotation on business service methods.\n\n#### Cache Management\nThe project contains examples of the `@Cacheable`, `@CachePut`, and `@CacheEvict` annotations on business service methods.\n\n#### Scheduled (Batch) Processes\nThe project illustrates the use of the `@Scheduled` annotation and provides examples of cron, fixed rate, and fixed delay schedules.\n\n#### Asynchronous Processes\nThe project illustrates the use of the `@Async` annotation and provides examples of asynchronous methods with and without return values.\n\n#### Spring Security\nThe project provides examples of Spring Security integration.  The web service endpoints are secured using Basic Auth, backed by database authentication and authorization.  The project illustrates declarative authorization for resources by role.\n\n#### Spring Profiles\nThe project demonstrates how to use Spring Profiles to activate (or deactivate) application components and configuration.  The profiles illustrated are: batch, hsqldb, mysql, and docs.\n\n#### Unit Tests\nThe project contains unit and integration test examples for standard components such as business services or batch beans and examples for the web service endpoints using mock objects.  Examples using the Spring Boot `@*Test` annotations for specific test cases are provided.\n\n#### Actuator Monitoring and Management\nThe project illustrates the use of Spring Boot Actuator for application monitoring and management.  The application demonstrates the recording of custom metrics and the creation of custom health checks.  Also, custom Maven and Gradle project attributes are incorporated into the Actuator info endpoint.\n\n#### API Documentation Generator\nThe project includes [Spring REST Docs](https://spring.io/projects/spring-restdocs) integration to automatically generate API docs for the RESTful web service endpoints.  This feature may be activated using the *\"asciidoctor\"* Gradle task.\n\n#### Executable Jar\nThe Maven and Gradle builds produce a fully executable Spring Boot Jar file. The Jar file may be executed directly from the command line without the *\"java -jar\"* command and may be installed on servers as a Linux service.\n\n## Languages\n\nThis project is authored in Java.\n\n## Installation\n\n### Fork the Repository\n\nFork the [Spring Boot web services skeleton project](https://github.com/mwarman/skeleton-ws-spring-boot) on GitHub.  Clone the project to the host machine.\n\n### Dependencies\n\nThe project requires the following dependencies be installed on the host machine:\n\n* Java Development Kit 8 or later\n\nand, optionally, install:\n* MySQL 5.5 or later \\*\n\n\\* By default, the project uses the bundled, in-memory HyperSQL database (HSQLDB). However, MySQL may be used by activating the *\"mysql\"* Spring profile.\n\n### Spring Tool Suite or Eclipse\n\nThis project uses Checkstyle static code analysis and reporting to ensure contributions are formatted in a consistent manner.  To ease the burden for contributing software engineers, the Eclipse Java Code Formatter configuration is supplied.  The formatting configuration may be used in Eclipse, the Spring Tool Suite, or any derivative of the Eclipse IDE.\n\nThe Java Code Formatter configuration is located in the source at: `etc/eclipse/java-formatter.xml`.\n\nAfter importing the project into Eclipse, edit the project properties by selecting *Properties* from the *Project* drop-down menu.  Then, expand the *Java Code Style* menu and select *Formatter*.  Click the *Import* button to import the configuration file.  Next, expand the *Java Editor* menu and select *Save Actions*.  Ensure that the following selections are checked:\n* Enable project specific settings\n* Perform the selected actions on save\n  * Format source code\n    * Format all lines\n  * Organize imports\n\n### MySQL\n\nBy default the project uses the bundled, in-memory HyperSQL database. To switch from HSQLDB to MySQL, simply replace the *\"hsqldb\"* Spring profile with *\"mysql\"*. Do **not** use both profiles simultaneously. Specify the active profiles in the `application.properties` file.\n\nTo prepare MySQL, create an empty database schema and a user account.\n\nExecute the following SQL statement to create an empty schema for the project:\n\n```\nCREATE SCHEMA `skeleton` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;\n```\n\nExecute the following SQL statements to create a user account for the application. Review the database schema name, and user account credentials in the `application-mysql.properties` configuration file and make updates if necessary.\n\n```\ncreate user 'userName'@'localhost' identified by 'somePassword';\ngrant all on skeleton.* to 'userName'@'localhost';\n```\n\n## Running\n\nThe project supports [Maven](http://maven.apache.org/) and [Gradle](http://gradle.org/) for build, package, and test workflow automation.  \n\n### Maven\n\nThe following Maven goals are the most commonly used.\n\n#### spring-boot:run\n\nThe `spring-boot:run` Maven goal performs the following workflow steps:\n\n* compiles Java classes to the /target directory\n* copies all resources to the /target directory\n* starts an embedded Apache Tomcat server\n\nTo execute the `spring-boot:run` Maven goal, type the following command at a terminal prompt in the project base directory.\n\n```\n./mvnw spring-boot:run\n```\n\nType `ctrl-C` to halt the web server.\n\nThis goal is used for local machine development and functional testing.  Use the `package` goal for server deployment.\n\n#### test\n\nThe `test` Maven goal performs the following workflow steps:\n\n* compiles Java classes to the /target directory\n* copies all resources to the /target directory\n* executes the unit test suites\n* produces unit test reports\n\nThe `test` Maven goal is designed to allow engineers the means to run the unit test suites against the main source code.  This goal may also be used on continuous integration servers such as Jenkins, etc.\n\nTo execute the `test` Maven goal, type the following command at a terminal prompt in the project base directory.\n\n```\n./mvnw clean test\n```\n\n#### package\n\nThe `package` Maven goal performs the following workflow steps:\n\n* compiles Java classes to the /target directory\n* copies all resources to the /target directory\n* executes the unit test suites\n* produces unit test reports\n* prepares an executable JAR file in the /target directory\n\nThe `package` Maven goal is designed to prepare the application for distribution to server environments.  The application and all dependencies are packaged into a single, executable JAR file.\n\nTo execute the `package` goal, type the following command at a terminal prompt in the project base directory.\n\n```\n./mvnw clean package\n```\n\nThe application distribution artifact is placed in the /target directory and is named using the `artifactId` and `version` from the pom.xml file.  To run the JAR file use the following command:\n\n```\njava -jar example-1.0.0.jar\n\n...OR simply...\n\n./example-1.0.0.jar\n```\n\nBy default, the batch and hsqldb profiles are active.  To run the application with a specific set of active profiles, supply the `--spring.profiles.active` command line argument.  For example, to start the project using MySQL instad of HSQLDB and enable the batch process:\n\n```\njava -jar example-1.0.0.jar --spring.profiles.active=mysql,batch\n\n...OR simply...\n\n./example-1.0.0.jar --spring.profiles.active=mysql,batch\n```\n\n### Gradle\n\nThe following Gradle tasks are the most commonly used.\n\n#### bootRun\n\nThe `bootRun` Gradle task performs the following workflow steps:\n\n* compiles Java classes to the /build directory\n* copies all resources to the /build directory\n* starts an embedded Apache Tomcat server\n\nTo execute the `bootRun` Gradle task, type the following command at a terminal prompt in the project base directory.\n\n```\n./gradlew clean bootRun\n```\n\nType `ctrl-C` to halt the web server.\n\nThis task is used for local machine development and functional testing.  Use the `assemble` or `build` task for server deployment.\n\n#### assemble\n\nThe `assemble` Gradle task performs the following workflow steps:\n\n* compiles Java classes to the /build directory\n* copies all resources to the /build directory\n* prepares an executable JAR file in the /build/libs directory\n\nThe `assemble` Gradle task is designed to allow engineers the means to compile the project and produce an executable JAR file suitable for server environments without executing unit tests or producing other project reports.\n\nTo execute the `assemble` Gradle task, type the following command at a terminal prompt in the project base directory.\n\n```\n./gradlew clean assemble\n```\n\n#### build (default)\n\nThe `build` Gradle task performs the following workflow steps:\n\n* compiles Java classes to the /build directory\n* copies all resources to the /build directory\n* executes the unit test suites\n* analyzes unit test code coverage\n* produces unit test, code coverage, and other project reports in the /build/reports directory\n* prepares an executable JAR file in the /build/libs directory\n\nThe `build` Gradle task is prepares the application for distribution to server environments. The application and all dependencies are packaged into a single, executable JAR file.\n\nThis task is ideal for use on continuous integration servers such as Jenkins, etc. because it produces unit test, code coverage, and static analysis reports.\n\nTo execute the `build` Gradle task, type the following command at a terminal prompt in the project base directory.\n\n```\n./gradlew clean build\n```\n\nThe `clean` and `build` tasks are the default tasks for this project.  Therefore, simply typing `gradle` (or `./gradlew` to use the Gradle Wrapper) will produce the same result as `gradle clean build`.\n\n```\n./gradlew\n```\n\nThe application distribution artifact is placed in the /build/libs directory and is named using the project name and version from the `build.gradle` file.  To run the JAR file use the following command:\n\n```\njava -jar build/libs/example-1.0.0.jar\n\n...OR simply...\n\n./example-1.0.0.jar\n```\n\nBy default, the batch and hsqldb profiles are active.  To run the application with a specific set of active profiles, supply the `--spring.profiles.active` command line argument.  For example, to start the project using MySQL instad of HSQLDB and enable the batch process:\n\n```\njava -jar build/libs/example-1.0.0.jar --spring.profiles.active=mysql,batch\n\n...OR simply\n\n./example-1.0.0.jar --spring.profiles.active=mysql,batch\n```\n\n#### asciidoctor\n\nThe `asciidoctor` Gradle task performs the following workflow steps:\n\n* compiles Java classes to the /build directory\n* copies all resources to the /build directory\n* executes the unit test suites\n* generates [Asciidoctor](https://asciidoctor.org/) snippets in the /build/generated-snippets directory\n* generates HTML API Docs in the /build/asciidoc/html5 directory\n\nThe `asciidoctor` Gradle task generates API documentation using [Spring REST Docs](https://spring.io/projects/spring-restdocs).\n\nTo execute the `asciidoctor` Gradle task, type the following command at a terminal prompt in the project base directory.\n\n```\n./gradlew clean asciidoctor\n```\n\nThe API documentation is placed in the /build/asciidoc/html5 directory and the root document is named `index.html`.\n\n#### encodePassword\n\nThe `encodePassword` Gradle task executes the `BCryptPasswordEncoderUtil` utility class to encode password values which may be included in the sample database scripts.  The clear text password values are passed as a Gradle `-P` property arguments on the command line.\n\nTo execute the `encodePassword` Gradle task, type the following command at a terminal prompt in the project base directory.\n\n```\n./gradlew -q encodePassword -Pmainargs=\u003cpassword\u003e[,\u003cpassword\u003e]\n```\n\nThe value of the `mainargs` property is passed as the arguments to the Java main method of the `BCryptPasswordEncoderUtil` class.  Separate multiple passwords with a comma.\n\n**Example:**\n```\nCommand:\n./gradlew -q encodePassword -Pmainargs=clearTextPassword\n\nConsole Output:\nArgument: clearTextPassword     Encoded: $2a$10$/BxBDZJrjJ5k9KN7gERjd.IJOZDuVYMq0HxuurnTCILGL/vbrNmBe\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanstacks%2Fskeleton-ws-spring-boot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleanstacks%2Fskeleton-ws-spring-boot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanstacks%2Fskeleton-ws-spring-boot/lists"}