101 for REST API with Swagger, ASP.NET and C#

Short summary about my lessons learned for a REST API with Swagger, ASP.NET and C#.

Configuration

Open the file SwaggerConfig.cs. For the first demo, we name our app and enable the UI:

GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion(“v1”, “API Demonstration”);
})
.EnableSwaggerUi();

SwaggerUI

The SwaggerUI can be found under:

http://localhost:%5BPORT_NUM%5D/swagger

Documentation

If you need documentation for you methods, parameters or controller, you have to enable the XML documentation file:

swagger_doku

Remember the path, you will have to add it to your Swagger configuration. This all the other configurations it should look like this:

GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion(“v1”, “API Demonstration”);
c.IncludeXmlComments(string.Format(@”{0}\App_Data\API-Test.XML”, System.AppDomain.CurrentDomain.BaseDirectory));
})
.EnableSwaggerUi();

To use the documentation, you can commentary to every method. Remember, you can use HTML formatting.

swagger_docu2

Path Parameters

Path parameters are fixed elements of the URL and are not optional. They can be set by the Route element. Every parameter is configured via {} brackets and have to match with the method parameters:

[HttpGet]
[Route(“test/route/{para1}/{para2}”)]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(String))]
[SwaggerResponse(HttpStatusCode.BadRequest, Description = “Bad Request”)]
[SwaggerResponse(HttpStatusCode.NotFound, Description = “Not found”)]

public string test(string para1, int para2)
{

The Request URL looks like this:

http://localhost:50283/test/route/Hello/7

Query Parameters

Query parameters are not part of the base URL. If tw want para2 to be a query parameter, just exclude it from the Route:

 

[HttpGet]
[Route(“test/route/{para1}”)]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(String))]
[SwaggerResponse(HttpStatusCode.BadRequest, Description = “Bad Request”)]
[SwaggerResponse(HttpStatusCode.NotFound, Description = “Not found”)]

public string test(string para1, int para2)
{

The Request URL looks like this:

http://localhost:50283/test/route/Hello?para2=7

(This can also be done with para1)

Optional Parameters

If you want optional parameter, just add a default value for the parameter.

[HttpGet]
[Route(“test/route/{para1}”)]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(String))]
[SwaggerResponse(HttpStatusCode.BadRequest, Description = “Bad Request”)]
[SwaggerResponse(HttpStatusCode.NotFound, Description = “Not found”)]

public string test(string para1, int para2=0)
{

Validating DateTime

You will get a 404 – Bad Request, if you use DateTime within a path parameter like this:

http://localhost:50283/test/route/2017-05-26T12:30:00

You have to options.

1. Use a query parameter like this: http://localhost:50283/test/route?time=2017-05-26T12:30:00

2. Change your web.config:

<configuration>

<system.web>

<httpRuntime requestPathInvalidCharacters=”” requestValidationMode=”2.0″ />
<pages validateRequest=”false” />
</system.web>
..
</configuration>

Advertisements