UX fail: Swagger

Why do popular applications have such glaring deficiencies in usability? Case in point: Swagger.

In this case, the "user" is the developer trying to implement Swagger or the OpenAPI spec.

Swagger is the messiah of API documentation, come to save us all from bad APIs and poor documentation and to relieve us of the tedium of writing boilerplate API code. It has it all; an editor and interactive tester that verifies your API, a code generator that will produce boilerplate code in dozens of languages and a really nice way to make beautiful documentation of your API available to people who want to use your API. But to get all this you have to learn the OpenAPI (formerly Swagger) specification. That's not the worst thing, especially if you're starting from scratch, and the editor and tester definitely improve the quality of your APIs. It's worth it to learn the OpenAPI spec since you get a lot of benefit for the effort.

Here is some documentation of OpenAPI and how to write it using Swagger tools. You can download the tools and use them but the easier way to do it is use SwaggerHub online. As long as you make your APIs public, you can create and save up to 5 APIs. If you want to develop and store more than 5 APIs in SwaggerHub or make them private or allow collaboration by a team, you will pay a minimum subscription fee of $75 a month (5 users) and the fee goes up as you add more team members. Here is a tutorial for SwaggerHub.

Great tools, but what about the massive library of APIs that already exist? How do you improve them and provide useful documentation? Well, painfully.

Swagger has libraries to add to your existing APIs to display documentation along with your API, if you annotate your existing code properly. Annotating is tedious and implementing the libraries isn't simple, straightforward, or easy to understand thanks to the fact that the documentation and examples aren't very good for this. This shouldn't be a surprise since most developer documentation isn't very good; most authors make huge assumptions about the understanding or capability of the reader and make magical leaps in their explanations that skip over a lot of important stuff that the reader may not know. But when Swagger claims to be trying to make documenting APIs better so they're easier for consumers to understand, they should also make their documentation here better so developers can understand and implement it more easily without having to go to StackOverflow.

Most people write APIs either by writing the tedious and repetitive code by hand or writing the output in JSON (or XML) and using some kind of code auto-generator to write the code, which drastically alleviates the tedium and amount of time spent writing code. Their are benefits and drawbacks to both approaches.

Writing the code by hand gives you much more control over the output, but if you have a large API it gets tedious. Writing the output and generating a schema from it is beneficial because you start from the final result and work backward so you can adjust the output until it looks the way you want, then you just run a utility to generate the code, saving a lot of coding time. The drawback is that you have to understand how to modify the schema to get the code to do what you want. If you're trying to produce both JSON and XML output, this can get really tricky because of the differences in the way certain things like arrays are represented.

Java XML bindings have had useful tools for years—for example, XJC or Apache CXF—to generate code to consume and produce both XML and JSON from an XML schema (essentially what a Swagger/OpenAPI does for JSON).

If you want to generate Java objects and code from JSON or a JSON schema using Jackson, Gson, or Moshi Java libraries, there's a helpful website for that.

The difficulty is building the XML schema in the first place but that has been made easier by several online tools that will generate schemas from sample XML. Converting from XML to JSON can be painful, but there are also online tools to do that. If you pick only one format—XML or JSON—the auto-generated code works great. If you want to provide both and allow the consumer to choose based on the HTTP request header (JSON or XML) you need finesse; in other words, it's not easy.

A great feature of Swagger CodeGen is its ability to generate code in over a dozen popular programming languages, not just Java. Swagger wants you to develop your APIs by first learning the OpenAPI spec then using the OpenAPI spec to generate the code. That's great, and OpenAPI is not too difficult to understand, but what do you do for existing APIs that you would like to improve by creating an OpenAPI doc?

Swagger finally released a tool, Swagger Inspector, to allow you to provide the results from an existing API and have it auto-generate the OpenAPI spec for you. Great idea! Except it doesn't work. Well, it does, but the results are almost useless. If you follow the brief video tutorial (another here) you will end up with an entirely different result. All it generates is the very simple description and endpoint; something you could have done yourself in a few minutes. Where the bulk of the work lies is in describing the object schema(s) in the result; the actual fields and value types (string, number, boolean, array, etc.). Swagger Inspector does none of that, even though it would be pretty easy to do. Hopefully this will show up soon, because Inspector is essentially useless right now. Good idea; not very well developed.

See also:

FasterXML Jackson Tutorials here and here
JSON annotations for FasterXML

UX Fail: Slack

I wanted to add a link to a message in Slack that didn't have the full ugly URL. In other words, instead of:

https://www.mysite.org/my-blog/2017/10/this-is-the-thing-to-read?lang=eng

I wanted it to look like:

Here's my link

This is trivial in most email applications. Select the text, click on a tool that allows you to create a link for it and you're on your way.

But Slack isn't an email application, you say. Sure, but it's used for sending messages; sometimes fairly complex ones that we want to add some fairly simple formatting to so it doesn't look like a mess.

How to do this in Slack? So far I haven't figured it out. I know it's possible using the Slack API and Message Builder, but now I have to go learn the API and figure out how to use Message Builder, neither of which is documented in a way for mere mortals to understand. So now I have to invest hours of time to become an "expert" in an application just to do something that is fairly common and I expect (foolish me!) to do without much difficulty.

To do something even simpler like bolding or italicizing text, you have to learn Slack's cryptic markup language and put strange symbols in your text. Sure, there are hints underneath the message entry window for the symbols to use, but that's not a user experience most people are familiar with. We're looking for links or buttons above or below the editor. Markup is for people who enjoy wasting precious time memorizing every application's variation of markup and reading documentation to learn what it is.

Really, Slack? This is as good as your UX gets? Massive fail.

Try making stuff easy for people who don't want to spend an hour or a lot more having to become an expert in yet another stupid software application just so they can do something that's common and should be easy.

More Slack fails:

• Can't delete messages when I make a mistake or regret sending something.
• Pressing Enter automatically posts the message instead of just creating another paragraph which is what anyone who uses a keyboard to create a message, document, or email expects the Enter key to do.