In this case, the "user" is the developer trying to implement Swagger or the OpenAPI spec.
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
