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:
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.
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>
