1) Many people use Swagger to design (rather than document), meaning the Swagger comes before the code
2) Most people just prefer to write it out, since the tooling otherwise isn't necessarily great (especially for non-developers)
We ran a poll and "by hand" (either on Swagger Hub/Apiary, or locally) won by a landslide.
I believe the best use-case for Swagger is to develop the API (perhaps just defining the routes with payload and response, but without controllers), and then auto-generating the Swagger files. This way the API consumers always have an up-to-date documentation, and there is only one place which represents the current state of the API.
I used REST which forced me basically to dig deep into online documentation when I wrote a client, but was rather straight forward to implement a server with.
I used SOAP which forced me to write a giant WSDL file, but was rather nice to work with on the client side.
GraphQL seems to obliterate this problem with its auto discovery mechanisms, but I don't know too much about it.
I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch.
How long did it take to write API consumer libraries in twenty languages and update every one on API change?
If you don't care about that, then Swagger isn't a good idea for you. But I'd think really hard about whether you should care about it if you think you don't.
> the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch
Sure--but you didn't have to write it.
When does it make sense to issue API-specific client libraries for a plain ole RESTful API?
Authentication is a good basic example. Different APIs will have different requirements for authentication headers. Successful authentication frequently requires multiple steps, like an initial request to get a session token. Many APIs will also require your request to be signed according to their specifications, and to stuff that signature in a header with a special name.
Every API expects to receive data in its own format. I don't want to have to make a bunch of validators that lay on top of your data model. These can and should be provided, and Swagger makes that automatic.
As eropple states, if something is making me do all of that by hand, I'm already looking for something else that will allow me to just say "import project_lib; project_lib.authenticate(); ..."
If you're just talking about something that is read-only and that only emits a single field I care about, sure, no need for a library. Something like the free version of ipinfo.io would be a good example.
Stuff that's more complicated than that, yes, it needs a client library.
Any time you have a statically-typed language consuming you. Having to write my own Jackson declarations to pull in your API to a JVM project or my own DataContract barf for a CLR one is a quick way to make me hate you, and me hating you means I'm already looking for an alternative that isn't you that gets out of my way.
- "Just REST" doesn't actually encapsulate meaningful behaviors by itself. It's by no means complete. Swagger is a partial patch on this by trying to reduce the scope of what your API is supposed to be doing, and it's not perfect, but it's better than "welp, throw Grape at it."
- Most statically-typed languages are a pain in the ass when it comes to HTTP responses because those responses can't be reified without types, and returning JSON blobs that don't have mapping types on the other end super sucks. I can do it myself if I absolutely have to--but making me waste my time doing it is silly.
Yes it does: open a socket, speak HTTP, get some data back. Yeah you'll have to feed it into a JSON parser or whatever but apparently people consider that a lot of work now?
I do agree on the points with statically-typed languages. Finagling dynamic types in such a system is a PITA. But I do not see the need for autogenerating tooling if you're consuming REST from a dynamic language; all you've automated is the HTTP call and data parsing (which takes very little time to write oneself)
Maybe I've been living under a rock the past 10 years but REST has never required very much effort, either to implement or consume. Then out of nowhere I begin encountering all these weird-ass tools -- Swagger (and who the F named that one, Old Spice?), Grape, whatever. All this crazy software to do all these crazy things when... it's just HTTP and JSON over the wire :/
At some point people need to ask themselves, 'how much abstraction is too much abstraction?'
Swagger's real value-add to me is in a standard documentation format for REST APIs, but the last instance I used of Swagger made my work more difficult :/
For Swagger Codegen, you can also customize the mustache templates in whatever way you want (e.g. replacing 4-space with tab in C# client templates). The auto-generated code may sometimes look lengthy but we usually do it with reasons based on feedback from developers. Please share with us more via https://github.com/swagger-api/swagger-codegen/issues/new so that we can further improve the output.
You may find Swagger Codegen a huge time saver in use cases in which the endpoints are growing (e.g. from 20 endpoints in v1 to 40 endpoints in v2) and you will need to provide API clients in multiple langauges (e.g. Python, Ruby, PHP, C#, etc)
Disclosure: I'm a top contributor to Swagger Codegen
Personally, I don't understand why codegen is even necessary as opposed to a pure object-oriented client that works directly from the Swagger spec. Before I knew Swagger existed, I actually implemented such a client based on my own made-up spec.[0] It's relatively naive, but I attribute that more to my relative youth in development than to the concept itself.
It's definitely going to be faster to just write it at first. Swagger, and everything like it, is an investment.
>I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch.
That's auto-generated code for you. Can't rival humans (yet), but that doesn't automatically mean it's not useful.
Compare hand-rolled ASM with compiler-rolled ASM for an example. Human-written ASM will often be much more compact and readable, sometimes even more performant, but then you have to write ASM instead of letting the compiler do it for you.
OpenAPI-GUI [1] [2] is a visual editor / creator for OpenAPI / Swagger 2.0 definitions. It runs entirely client side in the browser.
It's certainly useful enough to start an OpenAPI definition by providing all the boilerplate. Later, as the definition increases in complexity you can cut-and-paste in the editor of your choice.
[1] https://mermade.github.io/openapi-gui [2] https://github.com/mermade/openapi-gui
Here's an example of a very simple collection: https://github.com/postmanlabs/postman-collection-transforme...
But, you can also go and have something like https://github.com/postmanlabs/postman-collection-transforme..., which is very well documented. The generated documentation for this is available too: https://docs.postman-echo.com
Disclaimer: I work at Postman.
Completely agree. This was one of the reasons I liked using hapijs and joi in the past; they combine to validate and setup your HTTP endpoints and the swagger documentation is literarily generated from that code and not some separate thing you have to write. Unfortunately, outside of that very specific space, very little seems to exist.
Hapijs has its own issues and it's rarely my goto node framework anymore but it's hard to beat doing documentation that way.
You can easily hang yourself many different ways. The idea with Swagger includes some rules, which is what makes it useful. If you don't want that, then why use it?
It would be nice if you didn't have to write HTML to write a web page, but that's a constraint that has pretty well known benefits to end users.
It's crazy to me that it's harder to write a Swagger file than it is to write the API itself. And there's a lot of tooling that benefits from Swagger, but... I've found they all work 80%. Codegen, documentation, etc get 80% of the way there.
(Also, OAS 3 has linking, which is very similar to your hypermedia complaint)