Some changes in readme.md (f453db17) · Commits · ARF / World Storage API Helpers / World Storage ASP.NET Server

readme.md

+44 −45

Original line number	Original line	Diff line number	Diff line
	# Description of version 1.0.0		# Description of version 1.0.0

	auto-generated ASP.NET server code		This project 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.

	includes description and code for a fully functional server with MongoDB integration

			It includes description and code for a fully functional server with MongoDB integration.

	# Prerequisites		# Prerequisites
	1. installed npm: https://phoenixnap.com/kb/install-node-js-npm-on-windows		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/		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		3. Installed docker (if you want to use it): https://www.docker.com/get-started


	# Generate or update the server		# Generate or update the server

	we provided the file `.openapi-generator-ignore` in `server`, which prevents openapi-generator to override some adapted files		We provided the file `.openapi-generator-ignore` in `server`, which prevents openapi-generator to override some adapted files.

	## auto-generate server code		## Auto-generate server code
	open a command shell and execute		Open a command shell and execute:
	```		```
	openapi-generator-cli generate -i arf005\API\openapi.yaml -g aspnetcore -o server		openapi-generator-cli generate -i arf005\API\openapi.yaml -g aspnetcore -o server
	```		```

	open the solution `Org.OpenAPITools.sln` (folder `server`) in Visual Studio		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`		Open `NuGet Package Manager` and add `MongoDB.Driver`.

	### File adaptations:		### File adaptations:
	change version number in all files if a new version is provided		Change version number in all files if a new version is provided.

	### folder `Controllers`:		### In the folder `Controllers`:
	change "`public class`" to "`public abstract class`"		Change "`public class`" to "`public abstract class`".

	compare files folder in "`ControllersImpl`" with the corresponding files in "`Controllers`" and adapt if necessary		Compare files folder in "`ControllersImpl`" with the corresponding files in "`Controllers`" and adapt if necessary.

	methods should be the same with "`override`" instead of "`virtual`"		Methods should be the same with "`override`" instead of "`virtual`".

	---		---

	#### - if files are missing (and only then):		#### - if 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.:		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`)		Change classnames by appending `Impl` to the original classnames (and change filenames accordingly) and inherit from original class in `Controllers` (instead of `ControllerBase`)

	and replace `virtual` by `override` with all methods.		..and replace `virtual` by `override` with all methods.

	Add		Add
	```		```
	@@ -50,17 +50,16 @@ Add
	using MongoDB.Driver;		using MongoDB.Driver;
	```		```

	Add a private readonly service class variable like in the already existing files		Add a private readonly service class variable like in the already existing files.

	Add a constructor with this service class variable like in the already existing files		Add a constructor with this service class variable like in the already existing files.

	remove sample code and replace it by using the appropriate methods of the corresponding classes in the folder `Services`		Remove sample code and replace it by using the appropriate methods of the corresponding classes in the folder `Services` (which you may be have to create).
	(which you may be have to create)

	---		---

	### folder `Models`:		### In the folder `Models`:
	add to the classes to be stored in the database (i.e. `Trackable.cs`, `WorldAnchor.cs`, `WorldLink.cs`) :		Add to the classes to be stored in the database (i.e. `Trackable.cs`, `WorldAnchor.cs`, `WorldLink.cs`) :
	```		```
	using MongoDB.Bson;		using MongoDB.Bson;
	using MongoDB.Bson.Serialization.Attributes;		using MongoDB.Bson.Serialization.Attributes;
	@@ -72,58 +71,58 @@ and at the value that is to become the MongoDB ID, add:
	[BsonRepresentation(BsonType.String)]		[BsonRepresentation(BsonType.String)]
	```		```

	### folder `Services`		### Folder `Services`
	the folder `Services` should contain one common class with the DatabaseSettings (`DatabaseSettings.cs`) and one with the database-access-methods (create, get, update, remove) for each API. If some are missing create them like the ones you find there. Be aware to add the reference to these in the file `startup.cs` in this case.		The folder `Services` should contain one common class with the DatabaseSettings (`DatabaseSettings.cs`) and one with the database-access-methods (create, get, update, remove) for each API. If some are missing create them like the ones you find there. Be aware to add the reference to these in the file `startup.cs` in this case.

	the naming in the DatabaseSettings is the same as defined in `appsettings.json`, which you have to extend when creating new classes in this folder. Change `appsettings.json` in the folder `docker` accordingly. Make sure that the ConnectionString for the database contains the correct IP address as specified in `docker-compose.yml`.		The naming in the DatabaseSettings is the same as defined in `appsettings.json`, which you have to extend when creating new classes in this folder. Change `appsettings.json` in the folder `docker` accordingly. Make sure that the ConnectionString for the database contains the correct IP address as specified in `docker-compose.yml`.

	### folder `wwwroot`		### In the folder `wwwroot`
	add in `openapi-original.json` in section `servers` the urls of the servers you want to use with swagger-ui		Add in `openapi-original.json` in section `servers` the urls of the servers you want to use with swagger-ui

	# MongoDB		# MongoDB
	if you don't have a MongoDB, follow the instructions in `readme.md` in `server/programs/MongoDB`		If you don't have a MongoDB, follow the instructions in `readme.md` in `server/programs/MongoDB`

	and put MongoDB in folder `server/programs/MongoDB` (download MongoDB as zip-file from https://www.mongodb.com/try/download/community and unzip the file into this directory, so that the bin-directory is in this folder)		...and put MongoDB in folder `server/programs/MongoDB` (download MongoDB as zip-file from https://www.mongodb.com/try/download/community and unzip the file into this directory, so that the bin-directory is in this folder).


	# Use in Visual Studio		# Use in Visual Studio
	make sure, that an instance of MongoDB is running		Make sure, that an instance of MongoDB is running.

	start application with IIS Express		Start application with IIS Express.


	# Use in Docker		# Use within a Docker
	remove the substring `src/Org.OpenAPITools/` in Dockerfile (if not already done)		Remove the substring `src/Org.OpenAPITools/` in Dockerfile (if not already done)

	open a command shell and generate docker by executing in `server/src/Org.OpenAPITools`:		open a command shell and generate docker by executing in `server/src/Org.OpenAPITools`:
	```		```
	docker build -t org.openapitools .		docker build -t org.openapitools .
	```		```

	## to start:		## How to start:
	the easiest way is to use docker-compose:		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`:		Open a command shell and use docker-compose (if necessary adapt docker-compose.yml) by executing in `server/src/Org.OpenAPITools`:
	```		```
	docker-compose up --force-recreate --remove-orphan --detach		docker-compose up --force-recreate --remove-orphan --detach
	```		```

	open http://localhost:8080/openapi/index.html in a web-browser, if you want to check the functionalities using SwaggerUI		Open http://localhost:8080/openapi/index.html in a web-browser, if you want to check the functionalities using SwaggerUI

	## to stop:		## How to stop:
	open a command shell by executing in `server/src/Org.OpenAPITools`:		Open a command shell by executing in `server/src/Org.OpenAPITools`:
	```		```
	docker-compose down		docker-compose down
	```		```

	## to dump database		## How to dump database
	execute the following command in docker:		Execute the following command in docker:
	```		```
	mongodump --db insert database_name --out /data-dump/`date +"%Y-%m-%d"`		mongodump --db insert database_name --out /data-dump/`date +"%Y-%m-%d"`
	```		```

	## to import database:		## How to import database:
	execute the following command in docker:		Execute the following command in docker:
	```		```
	mongorestore --db insert database_name insert path_to_bson_file		mongorestore --db insert database_name insert path_to_bson_file
	```		```
			No newline at end of file