Developer’s guide

This REST-API was developed in <language - version> from scratch, meaning that it is not based on a pre-existing tool | with the version <tool version> of the tool tool.

Dependencies

Last modified on : <DDth MMM. YYYY>

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

Name	Version	Description
Spring Boot Starter Web	`3.3.5`	Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container.
Spring Data JPA	`3.3.5`	Spring Data module for JPA repositories.
Lombok	`>=1.18.34`	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	`1.0.1`	Custom Java library with factorized code common between microservices from the MetaboCloud project.
Openapi Generator	`7.10.0`	OpenAPI Generator generates API client libraries, server stubs, documentation and configuration automatically, given an OpenAPI Specification.

Dependencies required to test the application

Name	Version	Description
Spring Boot Starter Test	`3.3.5`	Starter for testing Spring Boot applications with libraries including JUnit Jupiter, Hamcrest and Mockito.
Awaitility	`>=4.2.2`	A Java DSL for synchronizing asynchronous operations.

Dependencies required to build the OpenAPI documentation

Name	Version	Description
Springdoc	`2.6.0`	Java library that helps to automate the generation of API documentation for spring boot projects.

Unit and functional testing

Unit and functional tests are in the src/test/java directory. To run all tests, use the following command :

$ mvn test

Note

You can launch specific tests by using the argument -Dtest.

$ mvn test -Dtest=<name of the file>

Where <name of the file> is the file containing the tests you want to run without its extension

Documentation generation

To generate the ReadTheDocs documentation, Sphinx 7.4.7 is required with the following extension :

Name	Version	Description
Sphinx-rtd-theme	`2.0.0`	Sphinx extension for using the “Read the Docs” theme.
Sphinx Tabs	`3.4.5`	Sphinx extension for creating tabbed content when building HTML.
Sphinx Design	`0.6.1`	Sphinx extension for designing beautiful, screen-size responsive web-components.

Note

They can be installed using the following command :

$ 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 :

$ 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.

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 Classes documentation 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-<name of the microservice>.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, …)