################# Developer's guide ################# This REST-API was developed in **** from scratch, meaning that it is not based on a pre-existing tool | with the version **** of the tool ``_. .. _: url of the Git repo !!!! Dependencies ============ .. |SpringBoot_version| replace:: ``3.3.5`` .. |MicroserviceLib_version| replace:: ``1.0.1`` .. |OpenApiGenerator_version| replace:: ``7.10.0`` .. |SpringDoc_version| replace:: ``2.6.0`` .. |Lombok_version| replace:: ``>=1.18.34`` .. |Awaitility_version| replace:: ``>=4.2.2`` *Last modified on : * This API relies on several dependencies, listed in the ``pom.xml`` file, which are installed and managed by Maven during the application compilation. Dependencies required to build the application ---------------------------------------------- .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Spring Boot Starter Web`_ - |SpringBoot_version| - | Starter for building web, including RESTful, applications | using Spring MVC. Uses Tomcat as the default embedded | container. * - `Spring Data JPA`_ - |SpringBoot_version| - | Spring Data module for JPA repositories. * - `Lombok`_ - |Lombok_version| - | Java library that provides annotations to simplify Java | development by automating the generation of boilerplate | code. Used for the automatic generation of getters and | setters methods. * - `Microservice Core Lib`_ - |MicroserviceLib_version| - | Custom Java library with factorized code common between | microservices from the MetaboCloud project. * - `Openapi Generator`_ - |OpenApiGenerator_version| - | OpenAPI Generator generates API client libraries, server | stubs, documentation and configuration automatically, | given an OpenAPI Specification. Dependencies required to test the application --------------------------------------------- .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Spring Boot Starter Test`_ - |SpringBoot_version| - | Starter for testing Spring Boot applications with | libraries including JUnit Jupiter, Hamcrest and Mockito. * - `Awaitility`_ - |Awaitility_version| - | A Java DSL for synchronizing asynchronous operations. Dependencies required to build the OpenAPI documentation -------------------------------------------------------- .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Springdoc`_ - |SpringDoc_version| - | Java library that helps to automate the generation of API | documentation for spring boot projects. .. _Spring Boot Starter Web: https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-web .. _Spring Data JPA: https://mvnrepository.com/artifact/org.springframework.data/spring-data-jpa .. _Lombok: https://mvnrepository.com/artifact/org.projectlombok/lombok .. _Microservice Core Lib: https://unh-pfem-gitlab.ara.inrae.fr/pfem/libs/pfem-microservices-core-lib .. _Openapi Generator: https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin .. _Spring Boot Starter Test: https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-test .. _Awaitility: https://mvnrepository.com/artifact/org.awaitility/awaitility .. _Springdoc: https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui !!!! Unit and functional testing =========================== Unit and functional tests are in the ``src/test/java`` directory. To run all tests, use the following command : .. code-block:: console $ mvn test .. note:: You can launch specific tests by using the argument ``-Dtest``. .. code-block:: console $ mvn test -Dtest= Where ```` is the file containing the tests you want to run without its extension !!!! Documentation generation ======================== .. |Sphinx_version| replace:: ``7.4.7`` .. |SphinxTabs_version| replace:: ``3.4.5`` .. |SphinxDesign_version| replace:: ``0.6.1`` .. |SphinxRTD_version| replace:: ``2.0.0`` To generate the **ReadTheDocs** documentation, `Sphinx`_ |Sphinx_version| is required with the following extension : .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Sphinx-rtd-theme`_ - |SphinxRTD_version| - | Sphinx extension for using the "Read the Docs" theme. * - `Sphinx Tabs`_ - |SphinxTabs_version| - | Sphinx extension for creating tabbed content when building HTML. * - `Sphinx Design`_ - |SphinxDesign_version| - | Sphinx extension for designing beautiful, screen-size responsive web-components. .. _Sphinx: https://www.sphinx-doc.org/en/master/ .. _Sphinx-rtd-theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/ .. _Sphinx Tabs: https://sphinx-tabs.readthedocs.io/en/latest/ .. _Sphinx Design: https://sphinx-design.readthedocs.io/en/rtd-theme/ .. note:: They can be installed using the following command : .. code-block:: console $ pip install sphinx sphinx-rtd-theme sphinx-tabs sphinx-design Then, once Sphinx and its extensions are installed, the documentation can be generated by using the following command : .. code-block:: console $ sphinx-build -M html doc build The documentation is then generated in HTML and can be accessed from the ``build/html`` folder. !!!! Code organisation ================= The structure of the InDex REST API follows the Standard Directory layout created by **Maven**. .. code-block::console . ├── build_docker_image.sh ├── ci_settings.xml ├── doc │ ├── class_doc.rst │ ├── conf.py │ ├── developers_guide.rst │ ├── examples.rst │ ├── index.rst │ ├── overview.rst │ ├── query_rest_api.rst │ └── uml │ ├── class_diagram.png │ ├── class_diagram.puml │ ├── classes │ └── images ├── Dockerfile ├── LICENSE ├── pom.xml ├── README.md ├── src │ ├── main │ │ ├── java │ │ └── resources │ └── test │ ├── java │ └── resources └── target **build_docker_image.sh** Script to build the Docker image in local. **ci_settings.xml** CI/CD configuration. ``doc`` Directory containing the source of the documentation/UML. **Dockerfile** File used to build the Docker image of the application. **LICENSE** Licence of the application. **pom.xml** XML File at the root of the repository that contains information about the project, configuration details and dependencies needed, used by Maven to build the project. **README.md** README file giving an overview of the application. ``src/main/java`` : Source code of the Application (see :doc:`class_doc` for more detail). ``src/main/resources :`` Resources associated to the application. * **application-mesocentre.properties** : Configuration file of the application with the properties required to run it on the MetaboCloud production. * **application-pfem.properties** : Configuration file of the application with the properties required to run it on the PFEM dev server. * **application.properties** : Configuration file of the application with the properties required to run it in local. * **infos.properties** : Configuration file containing the metadata associated to the REST API. * ``static/`` : Folder containing the static files. * **metabocloud-.yaml** : OpenAPI specification file describing the InDex REST API. ``src/test/java`` : Source code of the unit tests. ``src/test/resources`` : Resources necessary to run the tests. ``target`` : Folder containing files generated during the compilation of the application (OpenAPI generator classes, Coverage report, ...)