readme.md

# Description of version 0.0.3

auto-generated ASP.NET server code

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


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

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-compose.yml
**/.openapi-generator-ignore

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

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

### - folder `ControllersImpl`:
create a folder `ControllersImpl` and copy all files from `Controllers` to `ControllersImpl`

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. 

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` 
(have a look into the above mentioned `additions.zip` for an example)

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

### - 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`
create the folder `Services` and have a look into the above mentioned `additions.zip` for an example

the folder `Services` should contain 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:
the easiest way is to use docker-compose:

if not already done (i.e. by using the above mentioned zip-file `additions.zip`):
* copy file `docker-compose.yml` and folder `docker` from the above mentioned zip-file `additions.zip` or
  * create a folder `docker` 
  * create a sub-folder `data-dump`
  * copy appsettings.json into the folder `docker` and adapt the connectionString for MongoDB for the usage in docker
  * create a file docker-compose.yml for the above created image and MongoDB-image or copy it from the above mentioned zip-file `additions.zip`

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**
```