Benefits of NSwag:

• Documentation based on XML code comments
• Interactive web-based API client using SwaggerUI3
• Ability to generate API client in a wide range of languages such as Typescript, C# and Java.

Getting started

In this post, we will set up NSwag in a .NET Core web API.

The first step is to add the NSwag.AspNetCore package to your API project.

dotnet add package NSwag.AspNetCore

The package contains the middleware you need to add and use Swagger in Startup.cs.

Inside the ConfigureServices method, register Open API document generation.

services.AddOpenApiDocument(document =>
{
    document.Version = "v1";
    document.Title = Configuration["API:Name"];
    document.Description = Configuration["API:Description"];

    // For APIs that use JWT authentication
    document.AddSecurity("Bearer", Enumerable.Empty<string>(), new OpenApiSecurityScheme
    {
        Type = OpenApiSecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = OpenApiSecurityApiKeyLocation.Header,
        Description = "Type into the textbox: Bearer {your JWT token}."
    });
    document.OperationProcessors.Add(new AspNetCoreOperationSecurityScopeProcessor("Bearer"));
});

If your API does not use JWT authentication, you do not need to add security configuration above. Adding this configuration produces authentication controls on the Swagger UI web interface.

The next step is to use the Open API and SwaggerUI3. Again in Startup.cs, add the following code to before you map your controllers:

app.UseOpenApi();

app.UseSwaggerUi3(cfg =>
{
    cfg.DocumentTitle = "My Awesome API";
});

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
});

That’s it! Swagger UI is now available on /swagger route.

You should see all of your API resources, operations and code comments you have been adding to controllers and objects exposed from your API.

Define SwaggerResponse

If you notice the accept header in SwaggerUI is not set to application/json.

This is be because Swagger does not know the return types of your endpoints. Setting SwaggerResponse on each controller action is a good habit to get into. After all, a tool is as good as you use it.

This is an example controller action:

[HttpGet]
[SwaggerResponse(typeof(IEnumerable<BrandDto>))]
public async Task<IActionResult> Get(string filter)
{
    var brands = await _brandRepository.GetAllAsync(filter);
    var dtos = _mapper.Map<List<BrandDto>>(brands);
    return Ok(dtos);
}

Hide a resource from SwaggerUI

For those “secret” resources that you do not want to show on the SwaggerUI, you can use the ApiExplorerSettings annotation.

[ApiController]
[Route("v1/[controller]")]
[ApiExplorerSettings(IgnoreApi = true)]
[Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
public class SecretController : ControllerBase
{}

This annotation also works on controller actions to hide individual endpoints.

Change swagger route

The default Swagger UI route is /swagger. I personally do not like it so I change it to /docs whenever I start a new API project.

app.UseSwaggerUi3(cfg =>
{
    cfg.Path = "/docs";
});

Rename swagger.json

In order to rename the default swagger.json specification file, you need to define your path in both the open api specification and the swagger UI.

The following example produces a specification file docs.json:

app.UseOpenApi(cfg =>
{
    cfg.Path = "/docs/{documentName}/doc.json"; ;
});

app.UseSwaggerUi3(cfg =>
{
    cfg.DocumentPath = "/docs/{documentName}/doc.json";
});

Expand resources

SwaggerUI allows us to control the way API resources are presented on the page. By default, DocExpansion property is set to none, meaning all resources and operations are collapsed.

I prefer displaying expanding resources and keeping operations collapsed, by setting DocExpansion to list. This achieves the look of Swagger Petstore.

app.UseSwaggerUi3(cfg =>
{
    cfg.DocExpansion = "list";
});

Preserve authentication header

SwaggerUI provides a way for users to authenticate with the API and save the token so that it is added to each request automatically.

While this is a great feature, the authentication token is wiped when the page is closed/refreshed.

Having researched online, I came across a pull request on the SwaggerUI GitHub repository. User @AmirBitaraf implemented a feature toggle the preserve authentication between page refreshes.

From what I can see online, this feature toggle has not been made available in NSwag. It is possible to add a key/value pair to the AdditionalSettings list available in UseSwaggerUi3 middleware.

app.UseSwaggerUi3(cfg =>
{
    cfg.AdditionalSettings.Add("persistAuthorization", true);
});

Customise object names

If you use DTO objects for exposing data in your API, you will find that SwaggerUI displays the class names as they are defined. In my opinion, including keyword DTO in a class name in the documentation just adds noise.

Fortunately, this can be changed with a custom schema name generator.

Inside Startup.cs, configure OpenApiDocument to accept a custom name generator for SwaggerUI.

services.AddOpenApiDocument(document =>
{
    document.SchemaNameGenerator = new NSwagNameGenerator();
});

NSwagNameGenerator overrides the Generate method to modify the class name.

internal class NSwagNameGenerator : DefaultSchemaNameGenerator, ISchemaNameGenerator
{
    public override string Generate(Type type)
    {
        return type.FullName.Replace("Dto", "");
    }
}

Inject custom JavaScript to SwaggerUI

If, for any reason you need to manipulate SwaggerUI HTML page, you can inject a JavaScript file. This would allow further modifications such as logo replacement, colour schemes etc.

app.UseSwaggerUi3(cfg =>
{
    cfg.CustomJavaScriptPath = "/docs/hello.js";
});

If you haven’t changed the default swagger route, your path would be /swagger/hello.js.

In order for the JavaScript file to be used correctly, you need to place it under wwwroot/docs/.

Also, enable serving static files in your API before using SwaggerUI middleware.

app.UseStaticFiles();

This approach also works for custom stylesheets, which is available with CustomStylesheetPath property.

Include XML documentation when building the project

Any code comment you add to your classes will appear on relevant operations within SwaggerUI interface. Usually, Visual Studio build places the XML documentation file inside the bin folder:

Project/bin/debug/.netcoreapp3.1/MyProject.xml

Swagger uses this file to populate its UI with your code comments. Since XML documentation is considered a dev artefact, this file is not included when the application is built remotely via dotnet build on Azure DevOps server.

We can include the XML documentation file by generating it on the project root and setting its Copy to output directory property to Alyways.

1. Right-click on Project and select “Edit project file”. Alternatively open csproj file in a text editor.
2. Set the DocumentationFile property to a desired file name. Ensure the file name appears on its own.
3. Save and rebuild your project.

<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
    </PropertyGroup>
    <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
     <DocumentationFile>MyProject.API.xml</DocumentationFile>
    </PropertyGroup>
...
</Project>

This forces Visual Studio to generate documentation XML on the root of the project. We can now include this file in the build output by adding the following to the csproj file:

<ItemGroup>
  <None Update="MyProject.API.xml">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>

You can alternatively use Visual Studio user interface to make the same change via file properties.

SwaggerUI will now show documentation when you publish your API.

Final thoughts

NSwag is an amazing tool that I use in all APIs that I work on. It saves a lot time when it comes to producing documentation and client code generation. Do you use NSwag or an alternative? I look forward to hearing your opinion in the comments!

The post Automate API Documentation with NSwag appeared first on onthecode.

Learn how to generate a database with a code-first flow using EntityFramework Core in a Web API project.

TL;DR: This article will show you how to build your Web API with the new ASP.NET Core 3.1 and how to integrate with EntityFramework Core in order to provide a backing database for retaining data. Following the steps described in this tutorial, you will end up building a simple Web API project, whose full code you can find in this GitHub repository.

Create an API in Visual Studio

The first step is to create an API solution in Visual Studio. If you already have a project in place, skip to the next step.

Before starting to create an API, ensure that you have Visual Studio installed. This will bring along the .NET Core SDK and required dependencies. These instructions are created using Visual Studio for Mac with .Net Core 3.1. If you are on Windows, the steps are likely to be similar.

In Visual Studio, click File > New solution and select API template.

Next step is to give your project a name and configure the template.

You should now see the project structure in Visual Studio solution explorer.

Go ahead and launch the API against a browser, which should open a new window with sample data coming from the WeatherForecastController.

Now that we have an API in place, we are ready to generate a database using EntityFramework Core.

Add NuGet packages

The following NuGet packages exist in the nuget.org package feed. This should already be configured in Visual Studio.

Microsoft.EntityFrameworkCore
Microsoft.EntityFrameworkCore.SqlServer
Microsoft.EntityFrameworkCore.Design

Navigate to Manage NuGet packages window by right clicking on the solution and search for the packages above.

You may be asked to install other EntityFrameworkCore.* packages as you install these packages.

Create database context

In order for EntityFramework to create tables for our model classes, we need to create a class that inherits from DbContext.

public class AppDbContext : DbContext
{
    public DbSet<Book> Books { get; set; }

    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options)
    {
    }
}

Through conventions, EntityFramework will recognise the DbSet properties declared in the context and create/update table SQL table definitions accordingly. AppDbContext should live in a folder called Data or Infrastructure, to help you establish nicely separated namespaces.

This is also a good place to define column restrictions, manual relationship setup etc. via OnModelCreating hook.

Register the context at Startup

The next step is to register the context with the Startup.cs file as shown below.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<AppDbContext>(cfg =>
                cfg.UseSqlServer(Configuration.GetConnectionString("DbConnection"))
        );

    // omitted for brevity..
}

Notice the call to UseSqlServer method, where I specify the connection string from the configuration file. By default, appsettings.json is the config file used in non-development environment, while appsettings.Development.json is used for development environment.

These configuration files should have relevant connection strings. An example of a development configuration is below.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "ConnectionStrings": {
    "DbConnection": "Server=localhost,1433;Database=MyDatabase;User=sa;Password=RandomPassword@1"
  }
}

Generate first migration

A migration contains a set of changes and a rollback plan for EntityFramework to execute. Every time you make a change to DbSet classes, a migration needs to be created to allow EntityFramework to keep the database up to date.

To generate your first migration, open a terminal window and navigate to project folder. Then run the migration command below.

cd myprojectpath
dotnet ef migrations add FirstMigration

Running commands above will create a Migrations folder in your project, containing files that has instructions for EntityFramework to generate the database.

Migrate database on startup

At this point, your database is still not created. That is because we have not instructed EntityFramework Core to run the first migration we generated.

I prefer to auto-migrate the database when the API starts, instead of manually running migrations. This has the added benefit of not having to run migrations against remote environments such as staging/prod. As soon as the API starts, the database will be created/migrated by EntityFramework.

The first entry point of the API, Program.cs, contains a Main method, which is responsible for building the web host to start the API. This makes it a great place to run our auto-migration code to keep the database up to date.

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    using (var scope = host.Services.CreateScope())
    {
        var services = scope.ServiceProvider;
        var context = services.GetService<AppDbContext>();
        context.Database.Migrate();
    }

    host.Run();
}

//.. rest of the code

The code above pulls out the context we registered in Startup.cs and invokes Migrate to run all of the migrations in the project.

When you run the API, the database should be created with tables matching DbSet properties in the context file.

The post Generating a SQL Database with Entity Framework Core in a Web API Project appeared first on onthecode.

Due to the same-origin policy, most browsers restrict making requests to different domains than the originally served the website. This is a security feature that prevents a harmful site from accessing sensitive data on other sites. If you are developing an API though, cross-origin requests (CORS) are something you want to allow to make sure client applications can use the API.

Using a named CORS policy has been my preferred approach to enable CORS in .NET Core. This is simply because it applies the CORS policy to all endpoints in the API.

Code snippet below shows that I am opening up the API to the whole world:

public void ConfigureServices(IServiceCollection services)
{
    services.AddCors(o => o.AddPolicy("CorsPolicy", builder =>
    {
        builder.AllowAnyOrigin()
            .AllowAnyMethod()
            .AllowAnyHeader()
            .AllowCredentials();
    }));
    ...
}
public void Configure(IApplicationBuilder app,IHostingEnvironment env)
{
    ...
    app.UseCors("CorsPolicy");
    ...
}

Unfortunately, this does not appear to work and I get the following error when an AJAX request is issued in Chrome:

[Error] Access to XMLHttpRequest at ‘https://api.com/end-point’ from origin ‘https://mywebsite.com’ has been blocked by CORS policy: Response to preflight request doesn’t pass access control check: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.

Safari on Mac OS logs the following errors:

[Error] XMLHttpRequest cannot load https://staging.xyz.com/api/orders due to access control checks.

[Error] Failed to load resource: Preflight response is not successful

AllowAnyOrigin affects preflight requests and the Access-Control-Allow-Origin header. It sets the header to be a wildcard '*', which is ignored by browser as it is considered insecure.

Solution

The solution is to avoid using AllowAnyOrigin when defining the CORS policy and specify the origins that will consume your API.

services.AddCors(o => o.AddPolicy("CorsPolicy", builder =>
{
    builder.WithOrigins("https://mywebsite.com")
        .AllowAnyMethod()
        .AllowAnyHeader()
        .AllowCredentials();
}));

The origin can be a full domain such as above or a sub domain. It is also possible to use wildcard subdomains:

services.AddCors(o => o.AddPolicy("CorsPolicy", builder =>
{
    builder.WithOrigins("https://*.mywebsite.com")
        .SetIsOriginAllowedToAllowWildcardSubdomains();
}));

The post Enable CORS in .NET Core appeared first on onthecode.

Installing with SQL Server on a non-Microsoft platform was a dream just a few years ago. With the release of SQL Server 2017, Microsoft made it possible to directly install SQL Server on Unix-based operating systems. Since MacOS is Unix-based, we can directly install SQL Server on it using Docker.

In this post, we will install the preview version of SQL Server 2019 on macOS Mojave. We will use Docker to run SQL Server and look at available tools to work with a SQL database.

Install Docker

Firstly, download and install Docker Desktop for Mac. It is free for personal projects.

Install it by opening the .dmg file and move the Docker icon into Applications folder as shown below:

Launch Docker and you should see the docker icon in the MacOS menu bar.

Download SQL Server 2019

Open the Terminal and execute the following to pull the preview version of SQL Server 2019 container image for Ubuntu.

docker pull mcr.microsoft.com/mssql/server:2019-latest

The container image is a substantial download (~2GB) so it might take a while.

Consider making yourself a cuppa in the mean time!

Install SQL Server

Install the downloaded docker image using the following in the terminal.

sudo docker run -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=MyStrongPassword@1' -p 1433:1433 --name sqlserver2019 -d mcr.microsoft.com/mssql/server:2019-latest

A few things to note here:

1. -e ACCEPT_EULA=Y indicates that you agree to Microsoft’s EUA (End User Licence Agreement).
2. -e SA_PASSWORD is where you set the system administrator password for SQL Server. The password must be at least 8 characters long and contain characters from three of the following four sets: uppercase letters, lowercase letters, numbers & symbols.
3. -p flag allows the 1433 to be used as the TCP port number.
4. --name sets the instance name to sqlserver2019.
5. -d runs docker in deamon mode, used to run the container in the background.

Once the command executes, you can confirm the installation by running docker ps -a

Start the container with command:

docker start sqlserver2019

Executing SQL Queries

Microsoft recommends the use of sqlcmd to connect to SQL Server on Mac.

Use the following command to start an interactive shell inside your newly installed container:

sudo docker exec -it sqlserver2019 "bash"

Once you are in the container, you can finally connect to SQL Server locally:

/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'MyStrongPassword@1'

If successful, you will get >1 response, which allows you to run SQL commands.

Execute the following SQL commands one by one:

CREATE DATABASE MyDatabase
SELECT Name from sys.Databases
GO

You can pretty much run any SQL command using sqlcmd.

Although the command line works well, I prefer to use a GUI-based application to manage databases. SQL Server Management Studio is my primary choice for managing databases on Windows but it comes to mac, I use SQLPro for MSSQL nowadays.

Another alternative is DataGrip from JetBrains, which is pretty close to SSMS experience in Windows.

Connection string example

If your application needs to connect to SQL Server locally, the following connection string will be useful:

Server=localhost,1433;Database=MyAwesomeApp;User=sa;Password=MyStrongPassword@1

So there you have it, you can now work with SQL Server databases natively on your Mac!

The post Installing SQL Server 2019 on MacOS appeared first on onthecode.