24 ms·
My problem with Swagger is almost the opposite... it solves the problem (APIs are very complicated to use!) by embracing this complexity with more complexity an
by gkoberger 10y ago
My problem with Swagger is almost the opposite... it solves the problem (APIs are very complicated to use!) by embracing this complexity with more complexity and more tools. Rather, I believe the solution is a push to just have simpler APIs.
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)
- BinaryIdiot 10y ago> 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. 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.
- mcescalante 10y agoI had these same issues. It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. 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.
- haikuginger 10y ago> 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. 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. [0]https://github.com/haikuginger/beekeeper https://github.com/haikuginger/beekeeper
- cookiecaper 10y ago>I had these same issues. It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. 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.
- eropple 10y ago> It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. 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.
- pbreit 10y agoIs whatever value people are getting out of client libraries provided by something generic like http://unirest.io http://unirest.io ? When does it make sense to issue API-specific client libraries for a plain ole RESTful API?
- eropple 10y ago> When does it make sense to issue API-specific client libraries for a plain ole RESTful API? 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.
- wing328hk 10y ago> 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. 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 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
- IncRnd 10y agoExcellent points that are like a breath of fresh air.
- fsargent 10y agoCheck out Stoplight.io for a good tool for managing swagger documentation. It's a lot easier than managing the YAML itself.
- k__ 10y agoAre there any good alternatives? 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.
- jwoah12 10y agoThis is GraphQL's killer feature imo. We describe our schema in easy-to-understand GraphQL Schema Language, use that text file to actually initialize our server, and the included GraphiQL UI automatically provides full documentation and interactive query tool. Our users no longer need nearly as much hand-holding to grok the data model.
- metachris 10y agoI've implemented Swagger with several APIs and agree that it's crazy complex and time-consuming to write Swagger files manually. 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.
- dvirsky 10y agoExactly. I wrote a project (https://github.com/EverythingMe/vertex https://github.com/EverythingMe/vertex) where you define the API with a semi declarative syntax in Go, and it just translates to swagger so you can generate documentation and playgrounds effortlessly. It worked very well.
- blazespin 10y agoSwagger yaml is hard to write? Hmm.. relative to the code that services it or consumes it, I find its pretty trivial.
- deleted 10y ago[deleted]
- Joeri 10y agoI use swagger annotations to generate a swagger json automatically from my REST services. It is quite effortless once set up.
- emidln 10y agoDo people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagger[1]). [0] https://github.com/metosin/compojure-api https://github.com/metosin/compojure-api [1] https://github.com/metosin/ring-swagger https://github.com/metosin/ring-swagger
- paulddraper 10y agoI didn't realize Swagger was meant to be an intermediate format.
- emidln 10y agoIt's not an intermediate format necessarily, but it reflects information already encoded in your route definitions. It seems silly to maintain that information twice in two different locations.
- darrelmiller 10y agoHence the reason for tools like swagger-inflector http://swagger.io/writing-apis-with-the-swagger-inflector/ http://swagger.io/writing-apis-with-the-swagger-inflector/ that allows you to drive routing directly from the OpenAPI definition
- gkoberger 10y agoIn my experience (we have a product where people upload Swagger files), most people write it by hand. There's two reasons: 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.
- dwaltrip 10y agoHow does a non-developer know how to document or design an API?
- cobookman 10y agoHave you looked at the protobuf grpc implementation. I find it way simpler than swagger. It also generates your server code as well.
- skyde 10y ago100% agree, if you can afford to use GRPC. It's much simpler than having to use swagger.
- fehguy 10y agoIsn't it more work to write tests than code? Not sure that's the best argument against a technology. 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.
- Meic 10y agoAt the risk of linking to another tool which will only get you 80% of the way there... 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 https://mermade.github.io/openapi-gui [2] https://github.com/mermade/openapi-gui https://github.com/mermade/openapi-gui
- czardoz 10y agoThis is why we developed the Postman Collection format. It's very simple, and expressive. More importantly, it's a way to impose _less_ constraints on the API Designer, while also being richly documented. Here's an example of a very simple collection: https://github.com/postmanlabs/postman-collection-transformer/blob/cbeee1f5ead9ded352a28aff4d97a90f279b4c77/examples/v2.0.0/no-body.json https://github.com/postmanlabs/postman-collection-transforme... But, you can also go and have something like https://github.com/postmanlabs/postman-collection-transformer/blob/cbeee1f5ead9ded352a28aff4d97a90f279b4c77/examples/v2.0.0/echo.json 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 https://docs.postman-echo.com Disclaimer: I work at Postman.