From 7a0c39b199f7150221e30763569ea8b2581da626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Marulanda=20P?= Date: Fri, 11 Oct 2024 00:41:59 +0200 Subject: [PATCH] Actualizado README.md --- README.md | 164 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 99 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index d0892bc..fc18a59 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,6 @@ [![DeepSource][deepsource-issues-badge]][deepsource-project-url] ![Docker Pulls][docker-pull-shield] ![Docker Image Version][docker-version-shield] -![Twitch nmarulo][twitch-shield] # Despensa-app - REST API @@ -38,111 +37,138 @@ Este proyecto proporciona los recursos a consumir por el [proyecto web][github-p -## Despliegue local +## Empezar a trabajar -- [Requisitos](#requisitos) -- [Empezar a trabajar](#empezar-a-trabajar) - - [Crear base de datos](#create-database) - - [Usando postman](#using-postman) - - [Trabajando en IntelliJ IDEA](#working-ingellij) +- [Despliegue en local](#despliegue-en-local) + - [Requisitos](#requisitos) + - [Configurar base de datos](#configurar-base-de-datos) + - [Compilar e iniciar el proyecto](#compilar-e-iniciar-el-proyecto) +- [Despliegue con docker](#despliegue-con-docker) +- [Trabajando en IntelliJ IDEA](#trabajando-en-intellij-idea) +- [Swagger](#swagger) +- [Usando postman](#usando-postman) -### Requisitos +### Despliegue en local -* [Java 21](https://jdk.java.net/archive/) -* [MySQL 8](https://dev.mysql.com/downloads/mysql/) -* [Maven 3.9.7](https://dlcdn.apache.org/maven/maven-3/3.9.7/binaries/apache-maven-3.9.7-bin.zip) (Opcional) -* [Wildfly 30](https://github.com/wildfly/wildfly/releases/download/30.0.0.Final/wildfly-30.0.0.Final.zip) (Opcional) +#### Requisitos -### Empezar a trabajar +* [Java 21][java-temurin-url] +* [MySQL 8][mysql-url] +* [Maven 3.9.7][maven-url] (Opcional) - -**Crear base de datos** +#### Configurar base de datos -- Creamos un usuario llamado `despensa_app` con la siguiente contraseña `despensa_app`. -- Creamos el esquema `despensa_app`. -- Automáticamente, al iniciar spring se ejecutarán los scripts [schema.sql](src/main/resources/db/schema.sql) - y [data.sql](src/main/resources/db/data.sql) +- Crear el esquema `despensa_app`. +- Establecer la contraseña del usuario `root` en la propiedad + `spring.datasource.password` del archivo [application.properties](src/main/resources/application.properties). +- Ejecutar manualmente los siguientes scripts: + - [schema.sql](src/main/resources/db/schema.sql) + - [data.sql](src/main/resources/db/data.sql) - -**Usando postman** +#### Compilar e iniciar el proyecto -- Puedes hacer un fork a las API en el siguiente enlace: +Abrir una consola en la raíz del proyecto y ejecutar los siguientes comandos: - [Run In Postman](https://app.getpostman.com/run-collection/3462094-24c69e86-2ae0-42da-a1f0-55d411d60ad6?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D3462094-24c69e86-2ae0-42da-a1f0-55d411d60ad6%26entityType%3Dcollection%26workspaceId%3Dfaa3b08b-5495-45eb-a53f-5d832821e4f2#?env%5Bdespensa-app%20-%20local%5D=W3sia2V5IjoidXJsIiwidmFsdWUiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXBpIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2FwaSIsInNlc3Npb25JbmRleCI6MH1d) +- `.\mvnw clean install` +- `.\mvnw spring-boot:run` - -**Trabajando en IntelliJ IDEA** +### Despliegue con docker +Con esta opción no necesitaremos instalar mysql y al iniciar siempre se ejecutarán los scripts (`schema.sql` y +`data.sql`), ya que la aplicación se iniciara con el perfil **dockerdev**. + +**Iniciar imagen de docker hub** + +```shell +docker compose -f compose.despensa-rest-api.yaml up -d +``` + +**Crear imagen e iniciar** + +```shell +docker compose up --build -d +``` + +### Trabajando en IntelliJ IDEA + +- [Community Edition](#community-edition) - [Clonar proyecto](#clonar-proyecto) -- [Configurar maven home path](#maven-home-path) -- [Compilar](#compile) -- [Ejecutar](#run) -- [Habilitar EditorConfig](#editor-config) -- [Establecer opciones de guardado](#on-save) +- [Establecer la ruta local de maven](#establecer-la-ruta-local-de-maven) +- [Configuraciones de ejecución](#configuraciones-de-ejecución) +- [Habilitar EditorConfig](#habilitar-editorconfig) +- [Establecer opciones de guardado](#establecer-acciones-de-guardado) - [spring-boot-devtools](#spring-boot-devtools) - -Clonar proyecto: +#### Community Edition + +Las siguientes indicaciones son para la versión Ultimate, pero en su mayoría también funcionan en la versión Community +Edition. + +Hay publicada una [demostración de despliegue local con la versión Community Edition][github-discussion-url] en la +sección de discusiones del repositorio. + +#### Clonar proyecto > File > New > Project from Version Control - -Establecer la ruta local de maven: +#### Establecer la ruta local de maven (No es necesario si se pretende usar `mvnw`) > File > Settings > Build, Execution, Deployment > Build Tools > Maven > - maven home path - -Compilar: +#### Configuraciones de ejecución -- `Run > Run...` - - `[spring-boot:run]`: Inicia el proyecto. - - `[clean,install]`: Compila el proyecto sin test. - - `[clean,install] Tests`: Compila ejecutando los test. +> Run > Run... - -Ejecutar aplicación: +- `[clean,install]`: Compila el proyecto sin test. +- `[clean,install] Tests`: Compila ejecutando los test. +- `[spring-boot:run]`: Inicia el proyecto. +- `App`: Inicia el proyecto. (Versión **IDEA Ultimate**) +- `docker compose`: Crear una imagen e inicia el proyecto. +- `docker compose (despensa-rest-api)`: Inicia la imagen de docker hub. -- `Run > Run...` - - `App` +#### Habilitar EditorConfig - > Si el usuario y contraseña, de la base de datos, es distinto a `root`, modificar la información de conexión - > del fichero `src/main/resources/application.properties` +Es necesario tener habilitado el soporte de EditorConfig: - -Habilitar EditorConfig +> Settings > Editor > Code Style +> - Enable Editor Config Support -- Es necesario tener habilitado el soporte de EditorConfig: +#### Establecer acciones de guardado - > Settings > Editor > Code Style - > - Enable Editor Config Support - - -Establecer acciones de guardado - -- Recomiendo tener activado las acciones de guardado: - - Reformat code - - Optimize imports +- Recomiendo tener activado las acciones de guardado: **Reformat code** y **Optimize imports**. > Settings > Tools > Actions on save - +> > Tener habilitado EditorConfig. - -Spring-boot-devtools +#### Spring-boot-devtools -- Activar la compilación automática del proyecto: +Activar la compilación automática del proyecto: > Settings > Build, Execution, Development > Compiler > - Build project automatically +### Swagger + +Al iniciar la aplicación podemos acceder a la siguiente URL y probar los recursos disponibles: + +- http://localhost:8080/swagger-ui/index.html?urls.primaryName=Public + +### Usando postman + +Como alternativa a swagger, puedes hacer un fork o visualizar la colección de recursos de la aplicación en siguiente +enlace: + +[Run In Postman][postman-url] + ## Contribuir Cualquier contribución que hagas será muy apreciada. -- Antes de empezar a codificar, lea las [directrices de contribución](CONTRIBUTING.md). +Antes de empezar a codificar, lea las [directrices de contribución](CONTRIBUTING.md). ## Agradecimientos @@ -162,8 +188,6 @@ desarrollar este proyecto. [deepsource-project-url]: https://app.deepsource.com/gh/despensa-app/despensa-rest-api/ -[twitch-shield]: https://img.shields.io/twitch/status/andyonthewings?style=flat-square&label=Twitch%20nMarulo&labelColor=A970FF&link=https%3A%2F%2Fwww.twitch.tv%2Fnmarulo - [docker-pull-shield]: https://img.shields.io/docker/pulls/nmarulo/despensa-app?style=flat-square&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fnmarulo%2Fdespensa-app [docker-version-shield]: https://img.shields.io/docker/v/nmarulo/despensa-app?sort=date&style=flat-square&label=Docker%20versi%C3%B3n&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fnmarulo%2Fdespensa-app%2Ftags @@ -171,3 +195,13 @@ desarrollar este proyecto. [github-milestone-shield]: https://img.shields.io/github/milestones/progress/despensa-app/despensa-rest-api/1?style=flat-square [github-project-web-url]: https://github.com/despensa-app/despensa-web + +[java-temurin-url]: https://adoptium.net/es/temurin/releases/?version=21 + +[mysql-url]: https://dev.mysql.com/downloads/mysql/ + +[maven-url]: https://dlcdn.apache.org/maven/maven-3/3.9.7/binaries/ + +[postman-url]: https://app.getpostman.com/run-collection/3462094-24c69e86-2ae0-42da-a1f0-55d411d60ad6?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D3462094-24c69e86-2ae0-42da-a1f0-55d411d60ad6%26entityType%3Dcollection%26workspaceId%3Dfaa3b08b-5495-45eb-a53f-5d832821e4f2#?env%5Bdespensa-app%20-%20local%5D=W3sia2V5IjoidXJsIiwidmFsdWUiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXBpIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2FwaSIsInNlc3Npb25JbmRleCI6MH1d + +[github-discussion-url]: https://github.com/despensa-app/despensa-rest-api/discussions/29