Swagger Awesomeness

Posted on by trailmax

This post will be a dumping ground of links, problems and solutions related to Swagger. I’ll be putting updates here as I go along

I’m starting a new project and we would love trying new things. This time we would like to jump on the whole Azure Api Applications with Swagger as a descriptor of API.

Great article “What is Swagger”

Here is the whole Swagger Spec – have a look what is possible.

Here is the pretty cool page with Swagger file editor

Tutorials for ASP.Net

For the most part, just follow the tutorials provided by Microsoft:

  1. Create basic app
  2. Deploy app
  3. Create a basic client

While working on a client, I had a problem from a get-go – when I right click on the Project -> Add -> Azure Api App Client, I had some exception thrown by VS. This was related to installation of nuget packages. When I installed Microsoft.Azure.AppService manually and then re-tried the same actions, everything worked.

When my client was ready, I could read a list of things from the API in 2 lines of code – pretty awesome, but creating new records did not quite worked – I had a very non-descriptive exception throw at me: Exception of type 'Microsoft.Rest.HttpOperationException'1[System.Object]' was thrown. Turned out that generated code was checking for returned HTTP Status code and was always expecting to see 200. However, in the tutorials when we create new objects we have returned status 201 Created or Request.CreateResponse(HttpStatusCode.Created).
The resolution to this problem was to tell Swagger all possible return status codes (see this document for details). To do this you could add XML notation as a comment above the methods (really? in 2015 add XML to comments? REALLY?). Or you could add [SwaggerResponse(HttpStatusCode.Created)] attribute on the Post method:

    [SwaggerResponse(HttpStatusCode.Created)]
    [HttpPost]
    public HttpResponseMessage Post([FromBody]MyModel model)
    {
        // do something

        return Request.CreateResponse(HttpStatusCode.Created);
    }

This will change the generated Swagger metadata and will allow for 201 to be returned by this method without throwing exceptions.

By the way, you can get Swagger metadata by going to http://mydomain.com/swagger/docs/v1. So if you are running your API service locally, you can get the description from http://localhost:55419/swagger/docs/v1 (note port number will be different on your machine).

You can save this response as a *.json file and when you create definitions for Azure Api Client, you can provide this file instead of a published Azure Api App. Same way you can do with any other API that uses Swagger.