Developer's guide ================= This REST API was developed in Java 17 with the version 1.06 of the tool `InChI`_. .. _InChI: https://github.com/IUPAC-InChI/InChI !!!! Dependencies required --------------------- This API rests on several dependencies : * **To build the application :** * `Spring Boot Starter Web 3.2.5`_ : Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container. * `InChI 1.06`_ : Binary program which generates InChIs and InChI Keys of molecules. * `Lombok 1.18.32`_ : Java library that provides annotations to simplify Java development by automating the generation of boilerplate code. Used to the automatic generation of getters and setters methods. * `Microservice Core Lib 1.0.1`_ : Custom Java library with factorized code common between microservices from the MetaboCloud project. * `Openapi Generator 7.2.0`_ : OpenAPI Generator allows generation of API client libraries, server stubs, documentation and configuration automatically, given an OpenAPI Specification * **To test the application :** * `Spring Boot Starter Test 3.2.5`_ : Starter for testing Spring Boot applications with libraries including JUnit Jupiter, Hamcrest and Mockito. * **To build the documentation :** * `Springdoc 2.5.0`_ : Java library that helps to automate the generation of API documentation using spring boot projects. * `Sphinx 7.2.6`_ : Tool to build this documentation. * `Sphinx-rtd-theme 1.3.0`_ : Sphinx extension to use the "Read the Docs" sphinx-rtd-theme/ .. _Spring Boot Starter Web 3.2.5: https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-web/2.7.17 .. _InChI 1.06: https://github.com/IUPAC-InChI/InChI .. _Lombok 1.18.32: https://mvnrepository.com/artifact/org.projectlombok/lombok/1.18.30 .. _Microservice Core Lib 1.0.1: https://unh-pfem-gitlab.ara.inrae.fr/pfem/libs/pfem-microservices-core-lib .. _Openapi Generator 7.2.0: https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin/7.0.1 .. _Spring Boot Starter Test 3.2.5: https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-test/2.7.17 .. _Springdoc 2.5.0: https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui/1.7.0 .. _sphinx 7.2.6: https://www.sphinx-doc.org/en/master/ .. _sphinx-rtd-theme 1.3.0: https://sphinx-rtd-theme.readthedocs.io/en/stable/ .. note:: All the dependencies are install and manage by Maven during the application compilation, except for the InChI binary program which is downloaded externally. !!!! 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 (e.g. InChIGenerationControllerTest) !!!! Code organisation ----------------- The structure of the InChI REST API follows the Standard Directory layout created by **Maven**. .. code-block:: console . ├── doc # Folder with the source of the documentation ├── Dockerfile ├── LICENSE ├── Makefile ├── pom.xml ├── README.md ├── src # Folder with the code source of the application │   ├── main │   │   ├── java │   │   │   └── fr │   │   │   └── metabocloud │   │   │   └── inchi │   │   │   ├── Application.java │   │   │   ├── controllers │   │   │   │   ├── core │   │   │   │   │ ├── AboutController.java │   │   │   │   │ └── RootController.java │   │   │   │   └── inchi │   │   │   │     └── InChIGenerationController.java │   │   │   ├── exception │   │   │   │   └── GlobalExceptionHandler.java │   │   │   ├── implementation │   │   │   │   └── InChIGenerationImpl.java │   │   │   └── utils │   │   │   └── ConfigUtils.java │   │   └── resources │   │   ├── local │   │   │   └── application.properties │   │   ├── mesocentre │   │   │   └── application.properties │   │   ├── pfem │   │   │   └── application.properties │   │   ├── conf.properties │   │   ├── infos.properties │   │   └── static │   │   └── metabocloud-inchi.yaml │   └── test │   ├── java │   │   └── fr │   │   └── metabocloud │   │   └── inchi │   │   ├── ApplicationTests.java │   │   ├── controllers │   │   │   │   ├── core │   │   │   │   │ ├── AboutControllerTest.java │   │   │   │   │ └── RootControllerTest.java │   │   │   │   └── inchi │   │   │   │     └── InChIGenerationControllerTest.java │   │   ├── data │   │   │   ├── model │   │   │   │   └── Parameters.java │   │   │   ├── providers │   │   │   │   └── GenerationProvider.java │   │   │   └── stub │   │   │   ├── JsonStub.java │   │   │   ├── MolStub.java │   │   │   └── SdfStub.java │   │   └── implementation │   │      └── InChIGenerationImplTest.java │   └── resources │   ├── confTest.properties │   └── input │   ├── Caffeine │   │   ├── Caffeine.mol │   │   └── Caffeine.sdf │   ├── Cholesterol │   │   ├── Cholesterol.mol │   │   └── Cholesterol.sdf │   ├── D-Glucose │   │   ├── D-Glucose.mol │   │   └── D-Glucose.sdf │   ├── MethylTryptophan │   │   ├── MethylTryptophan.mol │   │   └── MethylTryptophan.sdf │   ├── Sphinganine1Phosphate │   │   ├── Sphinganine1Phosphate.mol │   │   └── Sphinganine1Phosphate.sdf │   └── VitaminE │   ├── VitaminE.mol │   └── VitaminE.sdf ``doc`` Directory containing the source of the documentation ``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. ``src/main/java`` : Source code of the Application * *fr.metabocloud.inchi* : * **Application.java** : Enables to run the application using the Web framework SpringBoot. * *fr.metabocloud.inchi.controllers.core* : Package containing controllers associated to the REST API * **AboutController.java** : Controller for the endpoint "/about" to retrieve the metadata associated to the REST API * **RootController** : Controller for the root "/" of the REST API * *fr.metabocloud.inchi.controllers.inchi* : Package containing controllers associated to the tool InChI * **InChIGenerationController.java** : Controller for the endpoint "/generation" gor the generation of the InChI and InChI Key of a compound * *fr.metabocloud.inchi.exception* : Package managing the exceptions that can be thrown by the REST API * **GlobalExceptionHandler.java** : Global handler which manage exceptions for all controllers * *fr.metabocloud.inchi.implementation* : Package containing classes which implement methods to process the received requests * **InChIGenerationImpl.java** : Implementation for the endpoint "/generation" * *fr.metabocloud.inchi.utils* : Package containing model objects * **ConfigUtils.java** : Utils for configuring the path of the binary program ``src/main/resources :`` Resources associated to the application * ``local/`` : Resource for building the application to use it in local * **application.properties** : Configuration file of the application properties * ``mesocentre/`` : Resource for building the application to use it on the MetaboCloud production * **application.properties** : Configuration file of the application properties * ``pfem/`` : Resource for building the application to use it on the PFEM dev server * **application.properties** : Configuration file of the application properties * ``static/`` : Folder containing the static files * **metabocloud-inchi.yaml** : OpenAPI file describing the InChI REST API ``src/test/java`` : Contain the Java sources of the unit tests * *fr.metabocloud.inchi* : * **ApplicationTests.java** : Test on the main application * *fr.metabocloud.inchi.controllers.core* : Package containing tests on controllers associated to the REST API * **AboutControllerTest.java** : Tests on the controller for the endpoint "/about" to retrieve the metadata associated to the REST API * **RootControllerTest** : Tests on the controller for the root "/" of the REST API * *fr.metabocloud.inchi.controllers.inchi* : Package containing tests on controllers associated to the tool InChI * **InChIGenerationControllerTest.java** : Tests on the controller for the endpoint "/generation" * *fr.metabocloud.inchi.data.model* : Package containing the model used for tests * **Parameters.java** : Model with all available parameters to query the application * *fr.metabocloud.inchi.data.providers* : Package containing the providers used to import data into tests * **GenerationProvider.java** : Provider for the "/generation" endpoint * *fr.metabocloud.inchi.data.stub* : Package containing classes which store the input to used in tests * **JsonStub.java** : Store JSON response several compounds * **MolStub.java** : Store MOLs of several compounds * **SdfStub.java** : Store SDFs of several compounds * *fr.metabocloud.inchi.implementation*: Package containing tests on the implemented methods to process the received requests * **InChIGenerationImplTest.java** : Tests on the implementation for the endpoint "/generation" ``src/test/resources`` : Host the files that are not Java sources but are necessary to run the tests. * ``input/`` : Folder containing the input used to run the tests .. note:: A ``Controller`` is a class that implements operations defined by the API. It will receive the request, process it and send back the response. .. note:: The ``highlight`` is a source folder, the *italic* a package, and the **bold** a file.