first commit - version 0.0.3 (10d337eb) · Commits · ARF / World Storage API Helpers / World Storage ASP.NET Server

OpenAPI.yaml

0 → 100644

+220 −0

Original line number	Diff line number	Diff line
		openapi: "3.0.0"
		info:
		version: 0.0.3
		title: World Storage API
		description: API ensuring interoperability between an authoring tool and a World Storage service
		license:
		name: BSD-3-clause
		url: https://opensource.org/licenses/BSD-3-Clause
		servers:
		- url: http://localhost:8080
		paths:
		/ping:
		get:
		summary: Test the server availability
		responses:
		'200':
		description: OK
		/admin:
		get:
		summary: Get the version of the API
		operationId: getVersion
		responses:
		'200':
		description: OK world storage.
		content:
		text/plain:
		schema:
		type: string
		/trackables:
		post:
		summary: Create a trackable
		operationId: addTrackable
		tags:
		- trackables
		requestBody:
		description: the trackable to be added to the world storage
		required: true
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/trackable'
		application/xml:
		schema:
		$ref: '#/components/schemas/trackable'
		responses:
		'200':
		description: OK returns the UUID of the Trackable defined by the world storage.
		content:
		text/plain:
		schema:
		type: string
		'201':
		description: Null response
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'
		get:
		summary: returns the list of all trackables defined by the world storage.
		operationId: getTrackables
		tags:
		- trackables
		responses:
		200:
		description: OK returns all the Trackables defined by the world storage.
		content:
		application/json:
		schema:
		type : array
		items :
		$ref: "#/components/schemas/trackable"
		201:
		description: Null response
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: "#/components/schemas/Error"
		/trackables/{trackableId}:
		get:
		summary: Find a trackable by his ID
		operationId: getTrackableById
		tags:
		- trackables
		parameters:
		- name: trackableId
		in: path
		description: ID of the trackable to retrieve
		required: true
		schema:
		type: string
		responses:
		'200':
		description: "successful operation"
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/trackable'
		'400':
		description: "Invalid ID supplied"
		'404':
		description: "Trackable not found"
		delete:
		summary: Deletes a trackable
		operationId: deleteTrackable
		tags:
		- trackables
		parameters:
		- name: trackableId
		in: path
		description: trackable id to delete
		required: true
		schema:
		type: string
		responses:
		'200':
		description: OK
		'400':
		description: Invalid ID supplied
		'404':
		description: trackable not found
		components:
		schemas:
		trackable:
		type: object
		required:
		- UID
		- creatorUID
		- trackableType
		- trackableEncodingInformation
		- trackablePayload
		- unitSystem
		- trackableDimension
		- keyvalueTagList
		properties:
		UID:
		description: A Universally Unique IDentifier identifying the trackable
		type: string
		format: uuid
		example: c75f6324-77a0-11ec-90d6-0242ac120001
		creatorUID:
		description: A Universally Unique IDentifier identifying the creator of the trackable
		type: string
		format: uuid
		example: c75f6324-77a0-11ec-90d6-0242ac120003
		trackableType:
		description: Extensible list of trackable types possibly handled by complient World Storage implementation
		type: string
		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, OTHER]
		example: FIDUCIAL_MARKER
		trackableEncodingInformation:
		description: Identifies targeted framework and version of the format.
		$ref: '#/components/schemas/encodingInformationStructure'
		trackablePayload:
		description: The data provided to create the trackable in a specific format handled by the World Storage service.
		type: string
		format: byte
		example: "10110101"
		localCRS:
		description: Coordinate reference system of the trackable, a 4*4 matrix (rowmajor) represented by a float vector
		type: array
		minItems: 16
		maxItems: 16
		items:
		type: number
		format: float
		example: [-2, 1, -3, 4,
		4, 4, 4, 2,
		1, 0, -2, 1,
		-1, -2, 0, 0]
		unitSystem:
		description: Unit of length
		type: string
		enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
		example: M
		trackableDimension:
		description: Bounding box of the Trackable, {width, length, 0} for 2D trackables, {width, length, depth} for 3D trackables
		type: array
		items:
		type: number
		format: double
		minItems: 3
		maxItems: 3
		example: [1,5,0]
		keyvalueTagList:
		description: List of additional parameters to be stored with the trackable.
		type: object
		additionalProperties:
		type: array
		items:
		type: string
		minItems: 1
		example: { "author" : ["james","donovan"], "image" : ["skater"]}
		encodingInformationStructure:
		required:
		- dataFormat
		- version
		properties:
		dataFormat:
		description: Identifier of the target framework
		type: string
		enum: [HOLOLENS, ARKIT, ARCORE]
		example : "HOLOLENS"
		version:
		description: The version of the format
		type: string
		example : "1.01"
		Error:
		required:
		- code
		- message
		properties:
		code:
		type: integer
		format: int32
		message:
		type: string
		No newline at end of file

additions.zip

0 → 100644

+10.6 KiB

File added.

No diff preview for this file type.

View file

openapitools.json

0 → 100644

+7 −0

Original line number	Diff line number	Diff line
		{
		"$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
		"spaces": 2,
		"generator-cli": {
		"version": "5.3.1"
		}
		}

readme.md

0 → 100644

+231 −0

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

		auto-generated ASP.NET server code

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

		# Generate or update the server

		In the following, we distinguish between a server code generation from scratch and an update of an existing solution

		---

		# First generation

		We provide a zip-file `additions.zip` with a folder structure and some files to simplify your work.

		If you want to use it unpack `additions.zip` in this folder and continue with the instruction for an [update](#update).

		Otherwise skip the unzip operation and continue with the next step (if you like to, you can compare your version with the one in the zip-file afterwards)

		The zip-file additions.zip contains:
		* server/src/Org.OpenAPITools/Dockerfile - a corrected Dockerfile
		* server/src/Org.OpenAPITools/docker-compose.yml - for a stack of server and MongoDB
		* server/src/Org.OpenAPITools/Startup.cs - the adapted original auto-generated file
		* server/src/Org.OpenAPITools/appsettings.json - added database settings to the appsettings.json
		* server/src/Org.OpenAPITools/Services/ - contains C# code for accessing MongoDB
		* server/src/Org.OpenAPITools/ControllersImpl/ - for c# classes inherting classes from /src/Org.OpenAPITools/Controllers/
		* server/src/Org.OpenAPITools/docker/ - contains appsettings.json for the use in docker and folder data-dump for later dumping the database for transfer if desired
		* server/programs/ - contains a readme.txt about how to install and run MongoDB for Windows
		* server/data/ - empty folder for the databases of MongoDB
		* server/.openapi-generator-ignore - to prevent openapi-generator to override these files


		## auto-generate server code
		open a command shell and execute
		```
		openapi-generator-cli generate -i OpenAPI.yaml -g aspnetcore -o server
		```

		## set files to ignore
		open the file `.openapi-generator-ignore` in server

		add the following file and folder entries:
		```
		**/Startup.cs
		**/appsettings.json
		**/Dockerfile
		**/docker-compoese.yml
		**/.openapi-generator-ignore

		**/ControllersImpl
		**/Services
		**/programs
		**/data
		**/docker
		```

		## In Visual Studio:
		open `NuGet Package Manager` and add `MongoDB.Driver`

		### - folder `Controllers`:
		copy all files from `Controllers` to `ControllersImpl`
		In all files in the folder `Controllers` change `public class` to `public abstract class`

		### - folder `ControllersImpl`:
		change classnames by appending `Impl` to the original classnames (and change filenames accordingly) and inherit from original class in `Controllers`

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

		Add
		```
		using Org.OpenAPITools.Services;
		using MongoDB.Driver;
		```

		Add a private readonly service class variable, e.g.
		```
		private readonly TrackableService _trackableService;
		```

		Add a constructor with this service class variable, e.g.
		```
		public TrackablesApiControllerImpl(TrackableService trackableService)
		{
		_trackableService = trackableService;
		}
		```

		remove sample code and replace it by using the appropriate methods of the corresponding classes in the folder `Services`

		### - folder `Models`:
		in the files add:
		```
		using MongoDB.Bson;
		using MongoDB.Bson.Serialization.Attributes;
		```

		at the value that is to become the Database ID, add:
		```
		[BsonId]
		[BsonRepresentation(BsonType.String)]
		```

		### - folder `Services`
		contains one class with the DatabaseSettings and one with the database-access-methods (create, get, update, remove) for each API

		the naming in the DatabaseSettings is the same as defined in `appsettings.json `

		### - file `startup.cs`
		add
		```
		using Org.OpenAPITools.Services;
		using MongoDB.Bson.Serialization;
		using MongoDB.Bson;
		using MongoDB.Bson.Serialization.Serializers;
		using Microsoft.Extensions.Options;
		```

		add the following code in `public void ConfigureServices(IServiceCollection services)`:
		```
		BsonSerializer.RegisterSerializer(new GuidSerializer(GuidRepresentation.Standard));
		BsonDefaults.GuidRepresentationMode = GuidRepresentationMode.V3;
		// requires using Microsoft.Extensions.Options
		services.Configure<insert classname of DatabaseSettings in Services>(
		Configuration.GetSection(nameof(insert classname of DatabaseSettings in Services)));
		services.AddSingleton<insert interface of DatabaseSettings in Services>(sp =>
		sp.GetRequiredService<IOptions<insert classname of DatabaseSettings in Services>>().Value);
		services.AddSingleton<insert classname of service class in Services>();
		```

		replace
		```
		opts.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
		opts.SerializerSettings.Converters.Add(new StringEnumConverter
		{
		NamingStrategy = new CamelCaseNamingStrategy()
		});
		```
		by
		```
		opts.SerializerSettings.ContractResolver = new DefaultContractResolver();
		```

		### - file `appsettings.json`
		add Database settings in `appsettings.json`, like
		```
		"TrackableDatabaseSettings": {
		"CollectionName": "Trackables",
		"ConnectionString": "mongodb://localhost:27017",
		"DatabaseName": "TrackablesDatabase"
		},
		```

		## MongoDB
		if you don't have a MongoDB add the folders
		* server/programs/MongoDB (for MongoDB)
		* server/data/ (to store database of 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)


		---

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

		### - folder `Controllers`:
		change `public class` to `public abstract class`

		compare files in `ControllersImpl` with the corresponding files in `Controllers`

		methods should be the same with `override` instead of `virtual`

		### - folder `Models`:
		add:
		```
		using MongoDB.Bson;
		using MongoDB.Bson.Serialization.Attributes;
		```

		at the value that is to become the MongoDB ID, add:
		```
		[BsonId]
		[BsonRepresentation(BsonType.String)]
		```

		### Solution
		open `NuGet Package Manager` and add `MongoDB.Driver`


		---

		# Use in Visual Studio
		make sure, that in instance of MongoDB is running (have a look in the above mentioned zip-file `additions.zip`: in the sub-folder `programs/MongoDB` you find a description, of how to install and run MongoDB for Windows)

		start application with IIS Express

		---

		# Use in Docker
		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`:
		```
		docker build -t org.openapitools .
		```

		## to start:
		open a command shell and use docker-compose (if necessary adapt docker-compose.yml) by executing in `server/src/Org.OpenAPITools`:
		```
		docker-compose up
		```

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

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

		## 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