diff --git a/readme.md b/readme.md index bc84c31f94b24bf5d6c345bfe0c5b9b1505bf356..239c654ec05abb4110cc7e9b95e1dffc5d413f3f 100644 --- a/readme.md +++ b/readme.md @@ -1,17 +1,42 @@ -# Description of version 1.0.0 +*This repository is part of the outcomes of the Specialist Task Force 620 focusing on the authoring of a World Representation as part of the ETSI ISG Augmented Reality Framework architecture (https://www.etsi.org/deliver/etsi_gs/ARF/001_099/003/01.01.01_60/gs_ARF003v010101p.pdf).* +*The set of the World Representation authoring components includes:* -This project should be used to construct a complete ASP-Net REST server compliant to the ARF World Storage API. It uses auto-generated ASP.NET server code. We propose to use the open source OpenAPI-Generator for this. +*β€’ The C++ and C# source code for servers and clients generated from OpenAPI available here (https://forge.etsi.org/rep/arf/arf005)* + +*β€’ A Unity plugin and a Unity editor for authoring and accessing a World Representation hosted on a World Storage server.* + +*All these components are available under the ETSI Labs group β€œWorld Storage API Helpers”: https://labs.etsi.org/rep/arf/world-storage-api-helpers* + +*If you wish to contribute to this project or any other projects in the context of the [ETSI ISG Augmented Reality Framework architecture](https://www.etsi.org/committee/1420-arf), please refer to the ["How to get involved in an ISG" section on the ETSI website](https://www.etsi.org/how-to-get-involved-in-an-isg)* + +--- + +# Description + +This repo should be used to construct a complete ASP-Net REST server compliant to the ARF World Storage API. It uses auto-generated ASP.NET server code. We propose to use the open source OpenAPI-Generator for this. It includes description and code for a fully functional server with MongoDB integration. -# Prerequisites +## Repo Content + +| | File / Folder | Description | +|:-:|:--------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| +| πŸ“‚ | server | The folder where the library code will be generated, the openapi generator is set to not overwrite some files used to generate and initialiue the ASP.Net server system | +| πŸ“‚ | server/programs/MongoDB | This folder contains the MongoDB service. The World Storage database should be created or imported in a folder of your choice which path has to be editied in the .bat file | +| πŸ“‚ | server/src/Org.OpenAPITools | This is the location where the ASP.Net code will be generated | +| πŸ“‚ | server/src/Org.OpenAPITools/ControllersImpl | THis folder contains the code implementating the REST end-paths for the different objects in API | +| πŸ“‚ | server/src/Org.OpenAPITools/Services | This folder contains MongoDB database settings and access methods for each API | +| πŸ“‚ | arf005 | A submodule pointing to the git containing the API specification file | + +## Requirements + What you need: 1. Installed npm: https://phoenixnap.com/kb/install-node-js-npm-on-windows 2. Installed openapi generator with npm: https://openapi-generator.tech/docs/installation/ 3. Installed docker (if you want to use it): https://www.docker.com/get-started -# Generate or update the server +# Code Generation We provided the file `.openapi-generator-ignore` in `server`, which prevents openapi-generator to override some adapted files. @@ -23,13 +48,13 @@ Open a command shell and execute: Open the solution `Org.OpenAPITools.sln` (folder `server`) in Visual Studio: -## In Visual Studio: +## In Visual Studio Open `NuGet Package Manager` and add `MongoDB.Driver`. -### File adaptations: +### File adaptations Change version number in all files if a new version is provided. -### In the folder `Controllers`: +### In the folder `Controllers` Change "`public class`" to "`public abstract class`". Compare files folder in "`ControllersImpl`" with the corresponding files in "`Controllers`" and adapt if necessary. @@ -38,7 +63,7 @@ Methods should be the same with "`override`" instead of "`virtual`". --- -#### - if files are missing (and only then): +#### If some files are missing (and only then!) Copy them from folder `Controllers`, rename them (append `Impl`) and handle them like the already existing files, i.e.: Change classnames by appending `Impl` to the original classnames (and change filenames accordingly) and inherit from original class in `Controllers` (instead of `ControllerBase`) @@ -58,7 +83,7 @@ Remove sample code and replace it by using the appropriate methods of the corres --- -### In the folder `Models`: +### In the folder `Models` Add to the classes to be stored in the database (i.e. `Trackable.cs`, `WorldAnchor.cs`, `WorldLink.cs`) : ``` using MongoDB.Bson; @@ -99,7 +124,7 @@ open a command shell and generate docker by executing in `server/src/Org.OpenAPI docker build -t org.openapitools . ``` -## How to start: +## How to start The easiest way is to use docker-compose: Open a command shell and use docker-compose (if necessary adapt docker-compose.yml) by executing in `server/src/Org.OpenAPITools`: @@ -109,7 +134,7 @@ Open a command shell and use docker-compose (if necessary adapt docker-compose.y Open http://localhost:8080/openapi/index.html in a web-browser, if you want to check the functionalities using SwaggerUI -## How to stop: +## How to stop Open a command shell by executing in `server/src/Org.OpenAPITools`: ``` docker-compose down @@ -121,8 +146,8 @@ Execute the following command in docker: mongodump --db **insert database_name** --out /data-dump/`date +"%Y-%m-%d"` ``` -## How to import database: +## How to import database Execute the following command in docker: ``` mongorestore --db **insert database_name** **insert path_to_bson_file** -``` \ No newline at end of file +```