API documentation writers are in a bind and Swagger isn't the answer.
By Robert Delwood
A Lead API Documentation Writer
(This is a sidebar article to a three-part series about Swagger. The other articles will be posted in upcoming weeks.)
[Home] [Writing samples] [LinkedIn]Swagger has become a popular API creation suite and is being fousted as a documentation tool. I will try to show that Swagger is poor documentation tool, and that the API documentation writing community must demand better. I’m going to address each of several issues in separate articles, starting now with looking at documentation from an API documentation writer’s point of view.
The Swagger PetStore (https://petstore.swagger.io/) is their showcase example. With the motif of an online pet store, you can add and remove pets, buy and sell them, and manage users. You do this by clicking on calls, and adding different information, while using their provided credentials. They do this to show you how easy the process is and how shiney their documentation is. Because it’s their showcase, I’m going to assume this is the best they can do. It’s like food advertisements photographs offering mouth-watering pictures. It continues to our horror when we open the box and see the truly repulsive food inside. It’s like that, too. And that’s the problem.
The following is a portion of that pet store site.
To give Swagger credit, it has a pleasant interface, clear controls, and it’s easy to generate. I understand why people like it as a tools platform. Opening the box, however, starts revealing disgusting food, and makes me not understand why people like it as a documentation platform.
I’m going to try to make cases that:
I don’t have to look far to find evidence. As it turns out, it’s in their own showcase. The following are symptoms but the disease is insidious. It starts by noticing the bad grammar. This isn’t typically considered a fault of the software. It’s considered a fault of the writers. For example, there is no consistent capitalization. Is the object Pet or pet? This may seem like a minor issue, but in programmer-to-programmer documentation, details matter. JavaScript is case sensitive. That means, Pet may imply the name of an object class. But why does a reader of a technical document have to guess, suppose, or infer meanings? It’s less a case of inattention to details, and more of just being plain wrong.
Then you go one step further and bad grammar turns into unclear sentences. Sentences like Other values will generated exceptions, Creates list of users with given input array, and Returns a map of status codes to quantities are hard to understand. Finally, you get to the meaningless. Logs out current logged in user session. I’m sure it must have been clear in the author’s mind, but what does that sentence mean? All of this changes documentation from being an annoyance to being useless, or even worse, creating a frustrating developer experience. Dismissing bad grammar is like going into your favorite restaurant and dismissing seeing rats, cockroaches, and slime in the ice machine. Apparently since you haven’t actually seen them in your food yet, it’s all right.
I believe programmers wrote all these descriptions. These are typical mistakes a non-writer makes. I’d like to think that no technical writer would let these happen. An obvious solution is to let API documentation writers create the material in the first place. I’ll address that issue in a moment. The next best thing is to let editors edit the material. Again, another good idea. As a best practice, editors should always review all material anyhow. The problem is that whoever management was that allowed programmers to write the material in the first place, isn’t going to be open to editors poking around. Management thinks how much can go wrong in four words? Looking over this sample, plenty.
So why am I using all of these to make a case that the software, and neither a programmer nor a writer, is to blame? Because the software is designed to make these errors. Let’s look at how this works. The following is an example from a Swagger Java module.
@Path("/pet")
@Api(value = "/pet", description = "Everything about your Pets")
@Produces({"application/json", "application/xml"})
public class PetResource {
...
}
All lines beginning with the @ symbol are Swagger notations. The parameter description is the documentation output. The documentation is inlined with the code. That means the most likely person modifying this has to be a programmer. It’s not just that it’s convenient for them to add a comment while they’re there. Writers don’t often have write access to code. In fact, writers should never have write access to code. That’s a foundational principle of separating the documentation and the code.
But even if writers could modify descriptions, being in the code still discourages writers. If your application is no more complex than a pet store, then you’ll be fine. But take the example of needing longer text. If the description is even just two paragraphs, the display would look like this:
This gets ugly. Uglier still is the code:
@Path("/pet")
@Api(value = "/pet", description = ""Everything about your Pets. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Mauris tempor bibendum mi vitae hendrerit. Nullam pulvinar libero ac lectus placerat congue. Donec ullamcorper dignissim est,
sit amet condimentum quam tincidunt ac. Aenean vestibulum rutrum fermentum. Donec eget mauris pretium, tincidunt felis quis,
porta lectus. Vestibulum nec hendrerit tellus, a bibendum odio. Etiam nulla nisl, porta sit amet dignissim a, **pulvinar**
sed nisl. Aliquam dolor sem, malesuada tempor mauris nec, pulvinar elementum diam. Etiam non faucibus libero,
quis pharetra eros. Nam non mauris sagittis, convallis nulla in, vehicula massa. Sed a rhoncus nulla.
Phasellus vitae dapibus odio. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
Ut semper vitae elit vel laoreet. Sed pretium risus vitae lacus pellentesque scelerisque. Ut condimentum, velit in dictum laoreet,
massa dui condimentum quam, in mollis sapien orci et neque. Sed ultrices varius tortor id iaculis. Sed tempus justo sit amet arcu
bibendum condimentum. Ut pharetra laoreet lectus, sit amet elementum massa elementum nec. In hac habitasse platea dictumst. Aenean
molestie felis ut libero maximus consequat. Sed aliquet leo dolor, vel mattis ante sagittis a. Donec facilisis posuere lacus
non elementum."
")
@Produces({"application/json", "application/xml"})
public class PetResource {
...
In addition to the awkward length, the formatting becomes a problem. The description supports Markdown and some HTML, but that’s almost beside the point. Larger concerns are unintended mistakes, formatting, frequent updates, the lack of WYSIWYG displays, there’s no spell checkers, and mistakes are identified during a compile and not real time. These mistakes can be nuances. A quotation mark, a common character for technical writers, will break the build. The number of line returns matters with Markdown. For example, the two line breaks between the paragraphs in the example above are important and needs to be kept.
It’s clear that writers didn’t design this system, and no programmer bothered to ask them. This is all so 1980s to the point of being stultifying that we use it, more stultifying that we accept it.
This is made worse in that these changes are being made only lines away from production code. Unintentional mistakes are going to happen. These may be mistaken copy and paste items, an accidental hit of the keyboard, or an inattentive writing inserts. The attitude that everyone needs to be attentive is good but we can’t have a production system based solely on that.
Swagger and OpenAPI are the emperor's new clothes. We might as well say so. Their example is shoddily done, poorly written, and arrogant. They didn’t even bother to edit it. Perhaps they thought so patronizingly of us, or that we’d be so enamoured with their pretty colors that we wouldn’t notice. True, none of those are direct problems with the software. They are all symptoms. It’d be easy enough to dismiss or to overlook them as such, but they point to serious design flaws. Swagger has some good uses but for small teams. For professional applications, we need more. We need a system that:
We’re almost in the third decade of the 21st century and we don’t have a real API documentation system. The community must demand for better.