Add an authorization header to your swagger-ui with Swashbuckle

Out of the box there’s no way to add an Authorization header to your API requests from swagger-ui. Fortunately (if you’re using ASP.NET), Swashbuckle 5.0 is extendable, so it’s very easy to add a new IOperationFilter to do it for us:

public class AddAuthorizationHeaderParameterOperationFilter : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        if (operation.parameters != null)
        {
            operation.parameters.Add(new Parameter
            {
                name = "Authorization",
                @in = "header",
                description = "access token",
                required = false,
                type = "string"
            });
        }
    }
}

Now all you need to do is register it in your EnableSwagger call:

configuration
    .EnableSwagger(c =>
    {
        c.SingleApiVersion("v1", "Commerce Services - Discounts");

        foreach (var commentFile in xmlCommentFiles)
        {
            c.IncludeXmlComments(commentFile);
        }

        c.OperationFilter<ExamplesOperationFilter>();
        c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    })
    .EnableSwaggerUi(config => config.DocExpansion(DocExpansion.List));

Once that’s done it’ll give you an input field where you can paste your Authorization header. Don’t forget to add the word “bearer” if you’re using a JWT token:

Edit: I wrote this more than a year ago using Swashbuckle 5.2.1, it may not work with later versions.

The decline of Apple

Back in the 90s hardly anyone used Macs or Apple products. They had a small foothold in schools and graphic design shops but that was about it. The iPod was the beginning of their post-millenium rise – the 3rd generation iPod released in 2003 was the first Apple hardware I’d ever wanted, and I eventually purchased a 4th gen iPod in 2004.

ipod
The fourth generation iPod “photo” model

A few years later in 2007 the iPhone came out and completely changed what a smartphone was. Prior the the iPhone the best smartphone was probably a Blackberry, with it’s clunky little keyboard and tiny screen. But the iPhone with it’s giant glass screen and intuitive gestures was revolutionary.

history-of-iphone-3gs-hero
The iPhone 3GS (2009), the first iPhone I owned

There’s hardly any products I can think of that I could afford to purchase the best in the world of. Take cars for example. I can’t afford a brand new Ferrari. Or TVs – I couldn’t afford (or couldn’t justify buying) a top of the line whizz-bang TV. But a phone – yes! The iPhone at the time was the best phone any money could buy. Not that I gave a shit about having an awesome phone, all I wanted at the time was to have wikipedia in my pocket so that I could be a know-all at parties.

Both the iPod and later the iPhone made people, especially us geeks, open our eyes to how good Apple’s products could be. The Macbook Air made us realise that the lightest and sexiest laptop/notebook was also made by Apple. Apple started shipping with Intel processors! Within a couple of years Apple laptops were everywhere, even at conferences for us Windows developers.

I never considered myself an Apple fanboy, but here I am in 2017 typing this on my trusty Macbook Air, with my aging iPhone 5 alongside, and an iPad sitting on the windowsill (which I still never use). At the time of each purchase it wasn’t that I wanted to buy an Apple product, it was just that I wanted the best laptop/phone/tablet on the market at the time, and each of those happened to be made by Apple.

Amongst my geeky friends it was pretty much the same pattern. Mac laptops and iPhones for the most part. Not all though – some swore by Android phones.

In the last couple of years though, Apple have made a few key mistakes with their products which have seen my geek friends desert them, and I think it won’t be long before I too leave Apple products behind.

iWatch sucked

The first big Apple let down was the Apple Watch. Rumours had abounded for years that Apple would be bringing out a smartwatch that would change the world, just like the iPhone did. I was excited about it. Then when it was finally released, it was expensive and gimmicky. Hardly any of my geek friends bought one (hi Andy J, Alan, Alex).

No headphone port

Yep, another mistake was omitting the headphone port from the iPhone 7. Not a single iPhone buyer thought that was a good idea or a step forward. That small error was enough for us geeks to doubt that Apple knew what they were doing, and look at Android phones.

Downgrading the Macbook Pro

The killer mistake though was 2016’s Macbook Pro

  • More expensive
  • No USB 3.0 ports
  • No HDMI port
  • No SD card reader
  • No magsafe power
  • Similar spec CPU, memory and storage to the 2015 model
  • Lame touch bar

Although most users don’t use the F1-F12 keys on the top row of a QWERTY keyboard, us developers DO use them, so getting rid of those keys was a big deal.

See Benjamin Button reviews the new Macbook Pro

Now what?

In summary, Apple haven’t released anything amazing since Steve Jobs died.

So what’s a geek to buy in 2017 then? I don’t know – it’s not as straightforward as a couple of years ago. I usually go on my geek friends recommendations – on the phone front, Google Pixel phones are well regarded. iPhones are hanging on by their fingernails.

On the laptop front, NONE of my friends are buying new Macbooks. Microsoft(!) Surface Books or Surface Pros are looking like a good option. Windows laptops are making a comeback.

What now for Apple

For now, they’ve lost the geek crowd, and in technology where the geeks lead the world follows. Apple needs to release a new killer product to get us back. Or just drop the prices on their bloody phones and make a decent laptop again!

They have enough $$$ in the bank that they’re not gonna die any time soon, but until they win the geek crowd back I predict shrinking profits, maybe even losses, and a dropping share price for Apple (currently USD$132).

On music consumption

This morning I was thinking about how my music listening has changed over the years. The very first album I bought was Guns N’ Roses Appetite for Destruction, which I bought on a cassette tape with my pocket money for something ridiculous like $15 in 1987.

2zgvqex

I didn’t spend too much money over the years on cassettes cos back then we all used to dub them – pretty much everyone had a stereo with 2 tape decks – one for playing and the other for recording.

80s-boom-box-ghetto-blaster-tape-deck

A few years later CDs came out and wow, music got even more expensive. But the quality was worth it – no more tape hiss. However, I still didn’t spend a whole lot on music – I was still at high school, so the tape dubbing continued – except now the source was a digital quality CD instead of a tape :-) I remember getting Guns N’ Roses Use Your Illusion 1 AND 2 off my mate’s older brother (hi Ed!) this way.

Come 1997 (woah, 20 years ago) and I was studying computer science at university, and a friend showed me mp3s (hi Flip!). At first I didn’t get it – because HDD space was expensive, so I was like “nah, I don’t really wanna fill my hard drive with music”. But once I realised how easy it was to share music (no more tape dubbing!) I was sold. So I got me a 2Gb Bigfoot hard drive and I was like – wow, loads of space, bring it on.

2664533936_3a6dfbc8f4
Bigfoot hard drive

This was the start of a period of CD borrowing and ripping – where you’d “rip” a CD on your computer to convert it into mp3s. Back then on our 2x speed CDROM drives and Pentium 1 processors it would take about half an hour to rip the CD and then I think most of the night(!?) to compress the ripped CD to an mp3 album. Playing an mp3 on your computer (using Winamp) was very CPU intensive, it would take pretty much 100% of your CPU to play an mp3 so you couldn’t use it for anything else while playing.

I fleshed out my music collection by borrowing friends’ CDs and ripping them – then you’d meet up with another fellow ripper (hi Trent!) and share mp3s with them, by unplugging the hard drive from your computer, taking it over to their house, and plugging it into their computer. Even though the mp3s were a digital copy so in theory perfect copies, every now and then you’d come across a track with pops and clicks in it – from when someone with a crappy CDROM drive would rip something.

1999 and Napster came along. Peer to peer sharing of music over the Internet! Almost any album you wanted, available to download, for free! Although we only had 56k modems to connect to the Internet, it still meant you could download an entire album in about 2 hours – much quicker and easier than ripping! And then we started running the Linux version of Napster on the University’s computers, so we could pull down an album in about ten or 20 minutes.

A few years later I was working my first post-Uni job so now I had money to spend. I did have a guilty conscience over all that music I’d ripped off so I started buying CDs – which would get converted to mp3s straight away, then the CD would never get played again. I’d moved to Auckland and I started going to concerts – my loose rule was – if I have an album by a band, and they come to Auckland, then I should go see them live. That was my way of supporting an artist.

Anyway, back to the mp3s, in the early 2000s. I was never a straight-up music hoarder. I didn’t want to have any old shite in my collection – it had to be good, memorable music, that I would still like in a few years. I became extremely pedantic with my organising and naming of the mp3s. Every mp3 had to be named correctly, with full metadata (ID3v1 and V2 tags), the correct genre, album art. I used JRiver Media Center software to manage it all. That program could do everything – I even used my newfound VB skills to write a plugin for it.

audio_standard_view
JRiver Media Center

Every time I’d get an album (usually from Napster, or from copying friends music over our corporate network (hi Deano!)), I’d spend ages scrutinizing it – do I like it? Will I still like it a few years from now? If this album came on randomly, would I listen to it? If it came on publicly, would I be embarrased by it? If it met those criteria then it was worthy enough to be added to my library. I’d almost always have to rename it correctly and populate all the metadata. All of which took time and effort.

All this time I was still constrained to listening to these mp3s through a PC – which was OK. I had a PC hooked up to a stereo in my bedroom, and then at work I’d be working on a PC wearing headphones all day. But mp3s on the go wasn’t yet possible for me. Early portable mp3 players were clunky, prone to crashing, had crap interfaces, or just didn’t have the capacity to store my entire collection.

The first game changer that came out was Apple’s iPod in 2001. I remember when it came out – it took the mp3 world by storm, mainly because it was pretty and easy to use. It solved the problem navigating through 1000 songs thanks to its scrollwheel interface. The downside of it was you had to run a Mac computer to use it – and absolutely no one had one of those. Back then Apple was dead. No one had a Mac PC or laptop. The only place I’d seen them was in the Uni’s computer labs.

ipod

If only I’d bought Apple shares back then! I knew the iPod was a hit, but I didn’t think to invest in the company. It turned out to be the beginning of Apple’s turnaround. Back then their shares were around $1.50, now they’re $117.

The first iPod wasn’t big enough for me though – it was 5Gb and I probably had around 20Gb of music by then. But Moore’s law caught up to my music collection, and the 4th generation iPod with 60Gb capacity (and Windows compatibility) was the first one I bought, in 2004. At last, my music everywhere.

In 2010 I moved to the UK and first heard about Spotify, which some of my friends were using. I ignored it for a few years, because I was pretty happy with my mp3 collection, and because I thought they might get shutdown by the music industry (or just go broke), as so many other online music services had.

2014 and I started using Spotify at work, just to try it out. I realised that their playlists solve the problem of what to listen to – when you’ve got hundreds of albums to choose from picking one can be tough. Spotify then became my main source – I installed it on my iPad and that was our main source of music in the house.

So, alas, my carefully curated music collection became obsolete. Here it is, on my laptop right now, still frozen in 2014. The _2014 folder is for new music for curation.

screen-shot-2017-01-08-at-17-22-10

So, I’m a happy Spotify user. Until last week. My girlfriend bought me an Amazon Echo for Christmas, and the voice interface has me sold. I say “Alexa, play music”. And it replies “OK, here’s a station you might like: Adele”. And I’m usually fine with what it (she?) chooses. Alexa has further removed the choice – I don’t even need to think about which playlist to play. I just say “play music” and that’s it. I’ve gone from an avid music collector before to not really caring what I listen to now. Life’s too short to be tagging mp3s.

Anyway, I didn’t intend for this post to be so long – I was just going to write how Alexa has killed my mp3 collection and ended up going on a trip down memory lane. I’ve added a new “Musing” category to this blog as I have a few more topics in mind.

OnePlus 2 = poo

I’ve been a long time iPhone user, first with a 3GS in 2009 and then an iPhone 5 in 2012. So at 3+ years old my iPhone 5 was getting a bit long in tooth. My colleague Nick recently replaced his iPhone 5 with a OnePlus 2 and he was very happy with it. Envious of that big screen and also it’s relatively cheap price, I decided to give it a go. I also wanted to try out Android as I’d heard good things.

DSC04123.0

I wasn’t impressed.

On the phone hardware side: The ringtone was quiet and the vibration unnoticeable when in a pocket. I managed to cause it to crash a few times by accidentally hammering the back button. It would get hot. And battery life wasn’t amazing.

On the Android side: I didn’t like Android’s way of doing notifications. Some web pages would run really slowly, and I don’t tolerate lag in a brand new phone.

As for that big screen – well, the apps didn’t feel optimized it – e.g. Facebook would still only show one news story at a time. Even with the smallest font there wouldn’t be much text on the screen at once, just lots of white space and big buttons. So the big screen felt wasted.

After 5 days I gave up on it and decided to go back to my iPhone 5, so I attempted to return the OnePlus. And that’s where their pathetic support team got involved. I started the returns process on Feb 16, and so far I’ve had 12 messages back and forward confirming my address, and confirming whether or not I want to return the cover, over and over. Finally today, March 11, I received an RMA form. So it’s taken almost a month of backwards and forwards with “Joey” and “Alex”. Let’s see how long it takes to get the money into my account.

Update: it took another month for the RMA to be processed, and I hadn’t heard anything until I chased them, so in total it took 2 months (and 18 emails) just to return the phone and get a refund.

Generating Swagger example requests with Swashbuckle

This is a follow on from my post from last year about Generating example Swagger responses.

It can also be useful to generate example requests, and in this post I will show you how.

Create a new SwaggerRequestExamplesAttribute

[AttributeUsage(AttributeTargets.Method)]
public sealed class SwaggerRequestExamplesAttribute : Attribute
{
    public SwaggerRequestExamplesAttribute(Type responseType, Type examplesProviderType)
    {
        ResponseType = responseType;
        ExamplesProviderType = examplesProviderType;
    }

    public Type ExamplesProviderType { get; private set; }

    public Type ResponseType { get; private set; }
}

Decorate your controller methods with it:

[Route(RouteTemplates.DeliveryOptionsSearchByAddress)]
[SwaggerRequestExamples(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(DeliveryOptionsModel), Description = "Delivery options for the country found and returned successfully")]
[SwaggerResponseExamples(typeof(DeliveryOptionsModel), typeof(DeliveryOptionsModelExample))]
[SwaggerResponse(HttpStatusCode.BadRequest, Type = typeof(ErrorsModel), Description = "An invalid or missing input parameter will result in a bad request")]
[SwaggerResponse(HttpStatusCode.InternalServerError, Type = typeof(ErrorsModel), Description = "An unexpected error occurred, should not return sensitive information")]
public async Task<IHttpActionResult> DeliveryOptionsForAddress(DeliveryOptionsSearchModel search)
{

Now implement it, in this case via a DeliveryOptionsSearchModelExample, which will generate the example data. It should return the type you specified when you called SwaggerRequestExamples.

public class DeliveryOptionsSearchModelExample : IExamplesProvider
{
    public object GetExamples()
    {
        return new DeliveryOptionsSearchModel
        {
            Lang = "en-GB",
            Currency = "GBP",
            Address = new AddressModel
            {
                Address1 = "1 Gwalior Road",
                Locality = "London",
                Country = "GB",
                PostalCode = "SW15 1NP"
            },
            Items = new[]
            {
                new ItemModel
                {
                    ItemId = "ABCD",
                    ItemType = ItemType.Product,
                    Price = 20,
                    Quantity = 1,
                    RestrictedCountries = new[] { "US" }
                }
            }
        };
    }

Finally, you’ll need to change the ExamplesOperationFilter we implemented in my previous post:

public class ExamplesOperationFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
    SetRequestModelExamples(operation, schemaRegistry, apiDescription);
    SetResponseModelExamples(operation, schemaRegistry, apiDescription);
}

private static void SetRequestModelExamples(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
    var requestAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerRequestExamplesAttribute>();

    foreach (var attr in requestAttributes)
    {
        var schema = schemaRegistry.GetOrRegister(attr.ResponseType);

        var request = operation.parameters.FirstOrDefault(p => p.@in == "body" && p.schema.@ref == schema.@ref);

        if (request != null)
        {
            var provider = (IExamplesProvider)Activator.CreateInstance(attr.ExamplesProviderType);

            var parts = schema.@ref.Split('/');
            var name = parts.Last();

            var definitionToUpdate = schemaRegistry.Definitions[name];

            if (definitionToUpdate != null)
            {
                definitionToUpdate.example = ((dynamic)FormatAsJson(provider))["application/json"];
            }
        }
    }
}

private static void SetResponseModelExamples(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
    var responseAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerResponseExamplesAttribute>();

    foreach (var attr in responseAttributes)
    {
        var schema = schemaRegistry.GetOrRegister(attr.ResponseType);

        var response =
            operation.responses.FirstOrDefault(
                x => x.Value != null && x.Value.schema != null && x.Value.schema.@ref == schema.@ref);

        if (response.Equals(default(KeyValuePair<string, Response>)) == false)
        {
            if (response.Value != null)
            {
                var provider = (IExamplesProvider)Activator.CreateInstance(attr.ExamplesProviderType);
                response.Value.examples = FormatAsJson(provider);
            }
        }
    }
}

private static object ConvertToCamelCase(Dictionary<string, object> examples)
{
    var jsonString = JsonConvert.SerializeObject(examples, new JsonSerializerSettings { ContractResolver = new CamelCasePropertyNamesContractResolver() });
    return JsonConvert.DeserializeObject(jsonString);
}

private static object FormatAsJson(IExamplesProvider provider)
{
    var examples = new Dictionary<string, object>
    {
        {
            "application/json", provider.GetExamples()
        }
    };

    return ConvertToCamelCase(examples);
}
}

Don’t forget to configure the ExamplesOperationFilter when you enable Swagger, as before:

configuration
    .EnableSwagger(c =>
    {
        c.OperationFilter<ExamplesOperationFilter>();
    })
    .EnableSwaggerUi();

Now that we’ve done all that, we should see the examples output in our swagger.json file, which you can get to by starting your solution and navigating to /swagger/docs/v1.

Capture

And the best part is, when you’re using swagger-ui, now when you click the example request in order to populate the form, instead of getting an autogenerated request like this:

Untitled

You’ll get your desired example, like this:

Capture2

 

Azure Emulator not working with SQL server alias

I just spent a few hours trying to figure out something that had me stumped.

In my local dev environment I’m building a web api which has a SQL database. The connection string for the database is an alias with a named pipe. If I set the web api as StartUp project in Visual Studio it works fine. (See this post for some tips on how to do that). But when I’d instead start the Azure emulator as the StartUp project it wouldn’t connect to the sql server, with the good ol’:

A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: SQL Network Interfaces, error: 26 – Error Locating Server/Instance Specified)

Eventually I figured it out. The alias was the problem, because if I changed the connectionstring to .\sqlexpress it worked fine.

Digging deeper, the problem was I had set up the alias on the “SQL Native Client 11.0 Configuration (32bit)” node, but I hadn’t added an alias on the “SQL Native Client 11.0 Configuration” node. So the fix was to create an additional Alias on the “SQL Native Client 11.0 Configuration” node.

sql

So it seems that debugging a web api locally may be a 32 bit process but debugging with the Azure emulator is a 64 bit process. Maybe?

Anyway, hope this helps someone.

Generating Swagger example responses with Swashbuckle

Swashbuckle is a tool for generating Swagger, the API description language, from your ASP.NET Web Api solution.
Using Swashbuckle, which provides Swagger-UI, you can create pretty living documentation of your web api, like this:
swagger

Documenting the Response

In this post I am going to show you how to document the Response, and a new way to generate some response examples.

You can specify the type of response for Swashbuckle a number of ways. Consider a simple API endpoint which returns a list of Countries:

public class CountriesController : DefaultController
{
    [HttpGet]
    public async Task<HttpResponseMessage> Get()
    {
        var resource = new List<Country>
        {
            new Country {Code = "AR", Name = "Argentina"},
            new Country {Code = "BR", Name = "Brazil"},
            // etc etc omitted for brevity
        };

        return Request.CreateResponse(HttpStatusCode.OK, resource);
    }
}

One way of describing the response code and content for Swashbuckle is using a combination of XML comments, and the ResponseType attribute, like so:

/// <response code="200">Countries returned OK</response>
[HttpGet]
[ResponseType(typeof(IEnumerable<Country>))]
public async Task<HttpResponseMessage> Get()
{

However, this only allows for one type of response.

If your API method can return multiple types, i.e. in the case of an error, then you can use the new SwaggerResponse attribute:

[HttpGet]
[SwaggerResponse(HttpStatusCode.OK, Type=typeof(IEnumerable<Country>))]
[SwaggerResponse(HttpStatusCode.BadRequest, Type = typeof(IEnumerable<ErrorResource>))]
public async Task<HttpResponseMessage> Get(string lang)
{

The Swagger 2.0 spec allows for examples to be added to the Response. However, at time of writing Swashbuckle doesn’t support this. Fortunately Swashbuckle is extendible so here is a way of doing it.

Create a new SwaggerResponseExamplesAttribute.

public class SwaggerResponseExamplesAttribute : Attribute
{
    public SwaggerResponseExamplesAttribute(Type responseType, Type examplesType)
    {
        ResponseType = responseType;
        ExamplesType = examplesType;
    }

    public Type ResponseType { get; set; }
    public Type ExamplesType { get; set; }
}

Decorate your methods with it:

[SwaggerResponse(HttpStatusCode.OK, Type=typeof(IEnumerable<Country>))]
[SwaggerResponseExamples(typeof(IEnumerable<Country>), typeof(CountryExamples))]
[SwaggerResponse(HttpStatusCode.BadRequest, Type = typeof(IEnumerable<ErrorResource>))]
public async Task<HttpResponseMessage> Get(string lang)

Now you’ll need to add an Examples class, which will generate the example data

public interface IProvideExamples
{
    object GetExamples();
}

public class CountryExamples : IProvideExamples
{
    public object GetExamples()
    {
        return new List<Country>
        {
            new Country {Code = "AA", Name = "Test Country"},
            new Country {Code = "BB", Name = "And another"}
        };
    }
}

Now you can add an ExamplesOperationFilter which implements Swashbuckle’s IOperationFilter.

public class ExamplesOperationFilter : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var responseAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerResponseExamplesAttribute>();

        foreach (var attr in responseAttributes)
        {
            var schema = schemaRegistry.GetOrRegister(attr.ResponseType);

            var response = operation.responses.FirstOrDefault(x => x.Value.schema.type == schema.type && x.Value.schema.@ref == schema.@ref).Value;

            if (response != null)
            {
                var provider = (IProvideExamples) Activator.CreateInstance(attr.ExamplesType);
                response.examples = FormatAsJson(provider);
            }
        }
    }

    private static object FormatAsJson(IProvideExamples provider)
    {
        var examples = new Dictionary<string, object>()
        {
            {
                "application/json", provider.GetExamples()
            }
        };

        return ConvertToCamelCase(examples);
    }

    private static object ConvertToCamelCase(Dictionary<string, object> examples)
    {
        var jsonString = JsonConvert.SerializeObject(examples, new JsonSerializerSettings() {ContractResolver = new CamelCasePropertyNamesContractResolver()});
        return JsonConvert.DeserializeObject(jsonString);
    }
}

And finally configure it when you configure Swashbuckle’s startup.

configuration
    .EnableSwagger(c =>
    {
        c.OperationFilter<ExamplesOperationFilter>();
    })
    .EnableSwaggerUi();

Now that we’ve done all that, we should see the examples output in our swagger.json file, which you can get to by starting your solution and navigating to /swagger/docs/v1.

response

And then, when you browse the swagger-ui at /swagger, instead of an autogenerated example like this:
response old

You’ll see your desired example, like this:
response new

Be sure to check out Part 2, where we again use Swashbuckle to generate example requests.