.net core swagger nswag

.Net Core 3 Razor Pages Integrate with Nswag

Matt 2019/12/30 00:48:45

0 2010

What Is Nswag

NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core... and more. It help us to document Web Api. If you're intresting in its history, try to read here, it describes more details.

Get Starting

Let's create a Razore Pages Web project.

Install NSwag.AspNetCore package

We can use Package Manage Console to install the package,

Install-Package NSwag.AspNetCore

or run donet command by using Cmd Console.

dotnet add package NSwag.AspNetCore

or still can install it from NuGet,

img "NuGet Nswag"

After the package installed, we configure it by default settings, followed this post here. Then run the project.

We might get an error: API Explorer not registered in DI....,

img "Nswag error"

ApiExplorer is MVC's abstraction to communicate with OpenAPI (aka Swagger) document generators. Unfortunately, what we created is a Razor Pages project, and Swagger needs Controller Middleware to work. Therefore, we add the code shown below,

services.AddRazorPages();
services.AddControllers(); // we added for Swagger

now, the project works fine.

Configure Swagger

While the project runs, we open

https://localhost:5001/swagger

to watch our api document. You might see,

SwaggerUi3

img "SwaggerUi3"

ReDoc

img "ReDoc"

they're all runs with default settings, for now. The default path name are all using "swagger". Note that, we can also make these two document UIs work together, and must to configure the path,

app.UseOpenApi();

app.UseSwaggerUi3(); // https://localhost:5001/swagger
app.UseReDoc(config =>
{
	config.Path = "/doc";
}); // https://localhost:5001/doc

with the code, two UIs can now work together by using different url.

Now, let us configure document basic information on Starup.ConfigureServices(IServiceCollection services)

services.AddOpenApiDocument(config =>
{
	// Document name (default to: v1)
	config.DocumentName = "YourDocumentName";

	// Document / API version (default to: 1.0.0)
	config.Version = "0.1.0";

	// Document title (default to: My Title)
	config.Title = "Razor Pages with Nswag";

	// Document description
	config.Description = "Razor Pages with Nswag, Description";
});

After the document info configured, we can see the detail appeared.

SwaggerUi3

img "SwaggerUi3"

that OAS3 tag means OpenAPI Specification Version 3.

ReDoc

img "ReDoc"

in ReDoc, the Document Name can NOT be seen directly. But we can observe the url, yes, the document name found.

https://localhost:5001/doc/index.html?url=/swagger/YourDocumentName/swagger.json

Xml Comment

For more Web API descriptions, we need to setup more detail to describe them. We document APIs with Xml Comment.

/// <summary>
/// get test data
/// </summary>
/// <remarks>
/// remarks here !!
/// </remarks>
/// <returns>returns test json data</returns>
[ProducesResponseType(typeof(int), Status200OK)]
[HttpGet]
public IActionResult Get() => Ok(new
{
	id = 0,
	data = "test things"
});

Nothing shows up, after we work hard to setup many things with Xml Comment. Why ?

img "nothings shows up"

Because, Swagger need xml remarks file to describe APIs. And let's do some works to generate that xml file. Edit Razor Pages web .csproj file first. Add a GenerateDocumentationFile markup.

<GenerateDocumentationFile>true</GenerateDocumentationFile>

After doing that, xml remarks file will be generated at bin$(Configuration)$(TargetFramework)$(AssemblyName).xml automatically when you build project(s). However, there's a problem occurred: Compiler Warning (level 4) CS1591 blow up. It's terrifying. We can ignore those warnings, or add another markup to avoid those things.