49 ms·

Problems with Swagger

• 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 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. 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.
  • IncRnd 10y ago
    Excellent points that are like a breath of fresh air.
  • fsargent 10y ago
    Check out Stoplight.io for a good tool for managing swagger documentation. It's a lot easier than managing the YAML itself.
  • k__ 10y ago
    Are 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 ago
      This 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 ago
    I'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 ago
      Exactly. 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 ago
      Swagger 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 ago
    I use swagger annotations to generate a swagger json automatically from my REST services. It is quite effortless once set up.
  • emidln 10y ago
    Do 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 ago
      I didn't realize Swagger was meant to be an intermediate format.
      • emidln 10y ago
        It'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 ago
          Hence 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 ago
      In 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 ago
        How does a non-developer know how to document or design an API?
  • cobookman 10y ago
    Have you looked at the protobuf grpc implementation. I find it way simpler than swagger. It also generates your server code as well.
    • skyde 10y ago
      100% agree, if you can afford to use GRPC. It's much simpler than having to use swagger.
  • fehguy 10y ago
    Isn'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 ago
    At 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 ago
    This 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.
• throwaway2016a 10y ago
  I'm surprised RAML isn't suggested as na alternative. http://raml.org/ http://raml.org/
  • misterbowfinger 10y ago
    Does it address the issues in the post?
    • jstoiko 10y ago
      The RAML 1.0 type system can help: http://adrobisch.github.io/blog/articles/hateoas-with-raml-10.html http://adrobisch.github.io/blog/articles/hateoas-with-raml-1...
  • curun1r 10y ago
    Or API Blueprint. Markdown is a really nice format for documenting your interfaces and you don't really need special tools to render the documentation for the web. Just checking the file into GitHub creates a link to human-readable documentation.
• mbesto 10y ago
  > The Problems with Swagger > This is a Swagger misusage problem, not a problem from Swagger per sé. The TL;DR is a list of gotchas and best practices the author has learned from using Swagger.
  • MyMan1 10y ago
    Almost.
• dqv 10y ago
  Here is a cached version as the site is currently giving me an HTTP 500: http://webcache.googleusercontent.com/search?q=cache:uQABqVCV2b0J:blog.novatec-gmbh.de/the-problems-with-swagger/+&cd=1&hl=en&ct=clnk&gl=us http://webcache.googleusercontent.com/search?q=cache:uQABqVC...
• Jdam 10y ago
  My problem with Swagger is the Swagger editor. It just works sometimes, but sometimes everything is just red for no reason. Tried with Safari, ChrOme, Ff on different Macs. Am I the only one who thinks this tool is unusable? Edit: Cheers to you guys at Novatec, have to take a look on InspectIT again.
  • cookiecaper 10y ago
    It's definitely buggy. I've had more luck with it in Firefox than other browsers. Refreshing and changing a line or two [usually] snaps it back into shape. Export your file frequently.
• jerven 10y ago
  This is a bit off topic, but I feel that Swagger etc... and actually most API docs are to human centric. You can't auto chain APIs together without a lot of developer intervention. The one thing I saw that allowed that was SADI services [1]. An awesomely pragmatic use of the semantic web. Pity it did not get picked up by Google etc... [1] http://sadiframework.org/ http://sadiframework.org/
• Yhippa 10y ago
  I really like the idea of HATEOAS but I have never seen hypermedia controls done in the wild across any companies I've worked for nor on any client projects. I think it's very cool but a lot of development patterns don't consider it.
  • richardwhiuk 10y ago
    I agree that HATEOAS is never deployed anywhere, but I think I'd go further than that. It's impossible for me to see how it would be possible to write a HATEOAS client, and I can't in practice see anyone doing so. Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort.
    • gamache 10y ago
      A few counterpoints as I drift by: The HAL hypermedia format is in use at Comcast, powering the Xfinity TV API. Not only does it take advantage of hypermedia and HATEOAS, it also splits requests/responses in order to make the most use of HTTP caches. https://boston2016.apistrat.com/speakers/ben-greenberg https://boston2016.apistrat.com/speakers/ben-greenberg Dunno if you're serious about not seeing how one could write a HATEOAS-driven client library or if I'm being trolled, but here's one that I wrote a couple of years ago: https://github.com/gamache/hyperresource https://github.com/gamache/hyperresource There are many others as well (especially for the HAL format).
      • richardwhiuk 10y ago
        I'm definitely not trolling - it's just that's not how clients work. I don't write a client by doing a random walk through the API until I get to the information I need, I want to call the API that I know I need to give me the information that I want, and for performance, I want it all to be returned on a single call ideally. e.g. If I want user B's playlist, I don't want to have to crawl: /friends/ => ['b': { 'links': {'info': '/friends/619'} }] /friends/619 => {'links': {'playlist': '/friends/619/playlist' } } /friends/619/playlist
• misterbowfinger 10y ago
  This seems more like, "issues with how Swagger is used in Java". A lot of Java developers are used to the SOAP APIs of yesteryear, and thus try to create clients with Swagger when they should be using gRPC or Thrift. In other language paradigms, I haven't faced this issue. Swagger is _just_ documentation, and a nice front-end on top. The Java annotations definitely make it easy to generate, though, I'll give it that.
  • xienze 10y ago
    > A lot of Java developers are used to the SOAP APIs of yesteryear, Hmm way to paint Java developers as old dinosaurs... > and thus try to create clients with Swagger when they should be using gRPC or Thrift. They're trying to create clients with Swagger because they've made a REST API (yes you can do that in Java!). If you're using gRPC or Thrift, you're not making a REST API.
    • cookiecaper 10y ago
      REST, if one insists on using it, should really be layered over top of something saner like gRPC or Thrift. Personally, I've always found REST troublesome and overhyped. There's always a few incidents where you spend hours trying to figure out why something isn't working before realizing you had the wrong method on the request. There's no reason the thing you actually want to do to a resource should be tucked away in some header that's not always easy to access or see, it's just asking for trouble.
      • djur 10y ago
        What HTTP servers and clients are you using that don't clearly log the request method? I've never seen one where it's easier to read the body of the request than the method.
        • cookiecaper 10y ago
          How about urllib, the Python default? def handle_thing(thing): r = urllib.request.Request(url='example.com', data={'stuff': 1}) return urllib.request.urlopen(r) Just one example. I know the tooling has improved somewhat since REST has become extremely common, so this is less of an issue now than it used to be (for example, most people use the Python requests module now, which makes it harder to use the wrong method (though many other HTTP libs still have the older urllib-style design)), but it's still annoying in principle. Combine with the fact that people tend to have different ideas about what the HTTP verbs and response codes mean, and it's pretty yucky. Compare with Thrift, where you define an interface, list the possible exceptions, and generate stubs that auto-handle all of this communication exchange for you. All you have to do is make sure that you're calling the correct function, which should be pretty obvious. This differs from setting the correct method in the HTTP headers in a couple of ways: first, HTTP clients usually assume a default method of GET. With a different protocol, there is no default "method", your action has to be defined somewhere. There will be no assumption (unless you code something implicit like this on top). Second, a more conventional method has increased code locality, meaning the code that affects the operation is likely to be in the same source file/area. You'll normally be calling an ordinary function name like SaveThing inside the application logic flow, and it will be easier to debug, easier to realize the problem, etc.; the operation to perform is not tucked away in some other contraption that affects the headers. Is it possible to design REST codebases so that such errors are hard to cause? Sure. But why do it the REST way and make it harder on yourself? It should be just as easy to see what function you're asking the API to perform on a resource as it is to see what you're sending it. The operation I want to perform is an intrinsic part of what I'm doing. There's no reason to separate it and make it hard. I'd even prefer url-based actions, like example.com/string_save, because then at least the resource and operation are defined in the same spot. A simple JSON envelope that has an "operation" key separate from a "data" key would make this easy, but then it's not in your header anymore, so it's not "real REST".
• zip1234 10y ago
  I think Swagger is nice--codegen makes it simple to generate API clients for various languages/frameworks. Saves a lot of time and potential sources of errors. If there is something easier/better/more reliable, then I am all ears, but Swagger keeps getting better.
• tschellenbach 10y ago
  Swagger is also a partial solution. I'd rather provide an API client library and clearly document how to use the client library and not the underlying REST API.
• tomc1985 10y ago
  One problem... it takes Swagger thirty-freakin-seconds to load its auto-generated whatever for Magento Community, and it has to do this every freakin time!
  • benmarks 9y ago
    That's... odd. Even running M2 off of DevBox on my Mac the swagger endpoint renders in 5-10s (first visit).
• deleted 10y ago
  [deleted]
• privacyfornow 10y ago
  I am working on auto generating clients with built in service subscription based discovery, shock absorbers and circuit breakers based on open api (swagger). We design our APIs with customer focus and therefore haven't run into some of these problems so far.
• andreygrehov 10y ago
  In terms of API documentation, the biggest problem is making sure the documentation is in sync with the actual code. I'm looking into using JSON Schema [1] along with Swagger and Dredd [2]. Making it all language-agnostic is a key. If anyone is doing anything similar, please, share your experience. [1] http://json-schema.org/ http://json-schema.org/ [2] http://dredd.readthedocs.io/en/latest/ http://dredd.readthedocs.io/en/latest/
  • clintonb 10y ago
    Ensuring documentation is in sync with code is straightforward if you have tooling in place to generate documentation from code. For example, at edX we use Django REST Framework and django-rest-swagger. Our Swagger docs are always up-to-date.
  • abraae 10y ago
    We have hundreds of APIs, and we use RAML + json schema. Since Swagger (OpenAPI) seems to be gaining ascendancy, I recently (some months ago) looked at migrating off of RAML, but at that time the Swagger guys had a philosophy that they would only support a subset of json schema. I get their reasons - they want to be able to generate code. But the things they didn't support (like oneOf - needed whenever you have a set of resources of varying types) are a show stopper for many APIs with even moderately complex payloads. For us at least, its more important to have a single source of truth for our APIs than to be able to generate code from the specs. Hence we remain on RAML (which seems great - just looking like its losing the popularity contest).
    • vasusen 10y ago
      We also use RAML + json schema primarily as the single source of truth. We use https://jsonschema.net https://jsonschema.net to generate json schema by providing it examples.
    • eleumik 10y ago
      in my opinion oneOf is bad for interoperability
• mr_tristan 10y ago
  I've found swagger codegen to be really, really inconsistent between different implementations. A few of them - I recall we had a team using Qt - didn't even generate compilable code. When I looked into the infrastructure of the codegen project, I found... mustache. Check it out yourself: https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources https://github.com/swagger-api/swagger-codegen/tree/master/m... Mustache is fine for doing a little view rendering, but for language generation... it's really obnoxious to use. Say you want to customize the output. Well, now you're basically replacing one of those magic .mustache files. And what's the model you use to generate those mustache files? Well, you got to look through the codebase for that. I ended up just not using swagger-codegen, and created my own StringTemplate based system, which got the job done a lot faster. The swagger core model was really janky to build logic around, however, so this system was really implementation specific. In the end, were I to do it all over again, I would have probably just built a different mechanism. And honestly, building your own damn little DSL and code generators for your use case will probably be faster then integrating Swagger. Especially if you do not use the JVM as part of your existing toolchain. I've not found anything to support multiple languages easily. If I were to do something today, I'd probably create a custom API DSL, custom code generators, with an output for asciidoctor (which is awesome) and example and test projects that test the generated code. Once you get the pipeline going the work is pretty straightforward.
  • wing328hk 10y ago
    > I've found swagger codegen to be really, really inconsistent between different implementations. A few of them - I recall we had a team using Qt - didn't even generate compilable code. When I looked into the infrastructure of the codegen project, I found... mustache. Yup, some generators (e.g. ActionScript, Qt5 C++) are less mature than the others (e.g. Ruby, PHP, C#). For the issues with Qt5 C++ generator, please open an issue via http://github.com/swagger-api/swagger-codegen/issues/new http://github.com/swagger-api/swagger-codegen/issues/new so that the community can help work on it. > Mustache is fine for doing a little view rendering, but for language generation... it's really obnoxious to use. Say you want to customize the output. Well, now you're basically replacing one of those magic .mustache files. And what's the model you use to generate those mustache files? Well, you got to look through the codebase for that. Instead looking through the codebase, you may also want to try the debug flag (e.g. debugOperations, debugModels) to get a list of tags available in the mustache templates: https://github.com/swagger-api/swagger-codegen/wiki/FAQ#how-to-debug-swagger-codegen https://github.com/swagger-api/swagger-codegen/wiki/FAQ#how-... I agree that mustache may not be the best template system in the world but it's easy to learn and developers seem pretty comfortable using it. > Especially if you do not use the JVM as part of your existing toolchain. One can also use docker (https://github.com/swagger-api/swagger-codegen#docker https://github.com/swagger-api/swagger-codegen#docker) or https://generator.swagger.io https://generator.swagger.io (https://github.com/swagger-api/swagger-codegen#online-generators https://github.com/swagger-api/swagger-codegen#online-genera...) to leverage Swagger Codegen without installing JVM. Thanks for the feedback and I hope the above helps. (Disclosure: I'm a top contributor to the project)
• hjacobs 10y ago
  While Swagger might not be perfect (some pain points are addressed with OpenAPI v3) it works IMHO pretty well for us (Zalando) and myself doing API first: * use a decent editor to write the YAML e.g. https://github.com/zalando/intellij-swagger https://github.com/zalando/intellij-swagger * do not write any boilerplate code and do not generate code (if that's possible in your env), e.g. by using https://github.com/zalando/connexion https://github.com/zalando/connexion (Python API-first) * follow best practices and guidelines to have a consistent API experience, e.g. https://zalando.github.io/restful-api-guidelines/ https://zalando.github.io/restful-api-guidelines/ Most importantly Swagger/OpenAPI gives us a "simple" (everything is relative!) language to define APIs and discuss/review them independent of languages as teams use different ones across Zalando Tech.
  • cimi_ 10y ago
    Easy is subjective, simple is objective. You probably meant easy ;)
• Touche 10y ago
  So many problems in programming are caused by trying to replace code with configuration. I've learned over time that the DRY principle can be harmful. Avoiding repetition is only good when it remains equally readable and powerful. Defining a DSL is almost alway a better idea (but more difficult) than defining a configuration format.
  • carapace 10y ago
    What is the difference between a DSL and a configuration format? I mean the essential difference. ;-)
• prodikl 10y ago
  > The rest of the URIs are provided by Hypermedia. I know this sounds awesome but in practice, it's really useful to have my swagger UI exposing the endpoints for our front-end developers to consume. What a pain it'd be for me to tell them "hit / and see what you get!" Having HAL links between resources is great and this discovery aspect of HATEOAS makes a lot of sense in development. But having a single entrypoint "homepage" to the API, when it comes to swagger, doesn't make sense. I ran into this when I asked another department for the endpoint to hit for certain data. I was given a swagger page with a bunch of "/status" endpoints that would then reveal additional endpoints. Who knows what rabbit hole I was sent down. I just needed the endpoint and the necessary parameters. If I were a third party or some outside developer consuming the API, it kind of makes sense. But our internal swagger docs really should reveal endpoints. I would feel like a big asshole if I asked my front-end co-worker to just "hit /status" and see if you get what you need! Disclosure: I don't use Swagger codegen. I only use the Docblock markup to document my API and generate the swagger.json that I display on our docs page.
• pibi 10y ago
  It looks like the perfect workaround is to use some middleware to autogenerate the Swagger docs, at least to keep code and documentation in sync. After a while I found myself doing the opposite, using Swagger to autoconfigure endpoints (https://github.com/krakenjs/swaggerize-express https://github.com/krakenjs/swaggerize-express) and even mongodb models (https://github.com/pblabs/swaggering-mongoose https://github.com/pblabs/swaggering-mongoose). Here is my actual reference architecture: https://github.com/pibi/swagger-rest-api-server https://github.com/pibi/swagger-rest-api-server Best thing about this approach is the clean separation between API definitions and the implementation (all over the stack), so the teams can just discuss about how to organize the resources and how to use them.
• carapace 10y ago
  I read "YAML, which I call XML for lazy people"... and closed the tab.
  • borplk 10y ago
    why?
• buremba 10y ago
  "..swagger repeats itself a lot with redundant annotations, it also leads to having more annotations than actual code." (Shameless plug) For this exact problem, we developed a Java library that makes easy to create RESTFul services that's highly integrated with Swagger. Here it is: https://github.com/buremba/netty-rest https://github.com/buremba/netty-rest We also tried hard to stick with Swagger-codegen but it's far from being stable so eventually we ended up creating a Slate documentation that demonstrates the usage of API with high level HTTP libraries for various programming languages. We convert Swagger spec to HAR representation, create the example usage of the endpoint with httpsnippet from the HAR (https://www.npmjs.com/package/httpsnippet https://www.npmjs.com/package/httpsnippet) and embed it in our Slate documentation using our Slate documentation generator. (https://github.com/buremba/swagger-slate https://github.com/buremba/swagger-slate) Here is an example: http://api.rakam.io/ http://api.rakam.io/
• dandlift 10y ago
  In my team we established a process where our first step is to write down the spec of the API, in swagger format. The spec is the source of thruth, and is written manually in yaml (that's not that painful). The implementation comes later. Unit tests check that it conforms with the spec. [1] We also have a fake API almost completely autogenerated from the spec that's quite useful for preliminary testing of the clients. Client code generation wasn't up to my expectations, but I've experimented with applying an handwritten template to a parsed spec and that seems viable. Swagger as a format might have its quirks, but the tooling is there and having it as the authoritive source of thruth paid off for Us. [1] https://bitbucket.org/atlassian/swagger-request-validator https://bitbucket.org/atlassian/swagger-request-validator
• banachtarski 10y ago
  I stopped reading after the author's silly interpretation of enums and why they "weren't" useful. The rantings of a beginner don't make for a good critique.
• pushECX 10y ago
  For those that find it tedious to write swagger by hand, I've been using Stoplight[1] at work and it's been working pretty well. You can create the spec from scratch, or use their proxy to auto-document your api. [1]: https://stoplight.io/ https://stoplight.io/
• janslow 10y ago
  Whilst Swagger Codegen doesn't create perfect libraries and some of the generators don't support all the features, once it's set up, it's just as easy to create a client for every language as it is for just one. For example, we create multiple client libraries, HTML documentation and a partial server (so we don't have to manually write the parameter parsing and models serializers). Another advantage is you can start consuming the API as soon as the API design is agreed, by using a generated mock server instead of waiting for the real one to be implemented.
• api 10y ago
  API Blueprint is much, much cleaner: https://apiblueprint.org https://apiblueprint.org Here's a renderer: https://github.com/danielgtaylor/aglio https://github.com/danielgtaylor/aglio It's less feature-rich than Swagger but the format is much less of a nightmare.
• tootie 10y ago
  XSD is bulletproof. Why don't we just keep using XSD?
  • sheeshkebab 10y ago
    maybe b/c it's for XML and not JSON, which most REST apis use.
    • tootie 10y ago
      If you don't use namespaces, you can validate JSON against an XSD. When I'm doing a REST API in Spring, I'll use and XSD and XJC (XSD Java Compiler) to generate model classes. The API endpoints are able to process those models as XML or JSON with 1 line of config.
  • abraae 10y ago
    Because people don't want bullet proof. They want quick wins that work straight away.
    • tootie 10y ago
      Quicker, easier, more seductive
    • Mikhail_Edoshin 10y ago
      "For every complex problem there is an answer that is clear, simple, and wrong." :)
• int_19h 10y ago
  TL;DR version: The first problem is that Swagger encourages codegen, and in static languages, said codegen is often unnecessarily restrictive when parsing input data. Adding a new enum member, and what that does to an existing Java client (that maps it to Java enum, which now has a missing member), is given as an example. The second and third problems are actually one and the same, and that is that Swagger doesn't do Hypermedia. If you don't know what that and HATEOAS is, this entire part is irrelevant to you. If you do know, and you believe it's a fad, then you wouldn't agree with any points in that complaint. If you do know and like it, then you already know what it is about (it's basically just rehashing the usual "why HATEOAS is the only proper way to do REST" narrative, with Swagger as an example). The last problem is that if you do API first (rather than YAML first), it's overly verbose, and can potentially leak implementation details into your spec.
  • jayd16 10y ago
    At its core, the complaint is just sour grapes from not planning ahead. You wrote the API with the guarantee of an enum, and then broke the gurantee and expected all the code relying on that guarantee to be fine. It doesn't work that way.
    • int_19h 10y ago
      Not quite; the point it's trying to make is that having an enum is not necessarily a guarantee that no new members will be added in the future, or at least it shouldn't be. I think it's half-right, in a sense that this is true for enums that are used for input values only. If the API adds a new enum value, it can also add handling for that value, so existing clients should just work (they just never use that new value). But if the enum is present in any output data, then adding a new value to it is a contract break, because existing clients can see it, and they don't know what they're supposed to do with it.
• bluejekyll 10y ago
  > To mitigate this problem just stop generating code and doing automatic deserialisation. No! WTF?! Just use generators that produce code that is resilient to a changing API. Why would you get rid of a huge productivity boost because the generator doesn't produce code you like? That's trading two hours of work to change the generator, for many multiple hours of reproducing the proper API, especially if you have many to support. I stopped reading right there. My personal biggest issue with swagger is that they threw the baby out with the bath water, reproducing XSD in Yaml, for no good reason. The UI they produced was nice, and that is probably the best feature of swagger. But the data format doesn't solve a new problem IMO, it just created a new standard that we all have to deal with. What is that now? Corba IDL, XSD, protobuf, thrift, avro, Swagger, Raml... I'm sure because of the flaws in each of those, we really should just use the new OpenAPI. Or just get rid of them all and go bare metal with Cap'n Proto. Oh but don't use code generators for any of those, because that would make it way too easy to support all of them with a single API </sarcasm>.
• kelnos 10y ago
  Oh, man. There is so much wrong with this article. Here we go: > The documents are written in YAML, which I call XML for lazy people No. That's ridiculous. XML (and JSON, for that matter) is designed to be read and written by machines, not humans. (If the design goal was actually primarily for humans to read and write it, the designers failed. Miserably.) YAML is a nice middle ground, in that it can be unambiguously parsed by a machine, but is also fairly pleasant and forgiving for humans to write. > The enum thing This is a problem with the code generators, not with Swagger as a spec. Any API definition format that allows enums (and IMO, all should) will have this "problem". Language-native enums are way better to deal with than stringly-typed things. An alternative might be to generate the enum with an extra "UNKNOWN" value that can be used in the case that a new value is added on the server but the client doesn't know about it. However, I would consider adding a value to an enum to be a breaking API change, regardless of how you look at it. What is client code expected to do with an unknown value? In some cases it might be benign, and just ignoring the unknown value is ok, but I'd think there are quite a few cases where not handling a case would be bad. I agree with the author that "adding a new element to the structure of the payload should NEVER break your code", but that's not what adding an enum value is. Adding a new element to the structure is like adding a brand-new property on the response object that gives you more information. The client should of course ignore properties it doesn't recognize, and a properly-written codegen for a Swagger definition should do just that. > Nobody reads the documentation anymore. The author admits this issue isn't specific to Swagger, and yet harps on it anyway. What? > No Hypermedia support ... Which means, you can change that business logic whenever you want without having to change the clients... Swagger is URI Centric Oh god. I don't care what Roy Fielding says. No one has embraced hypermedia. It's irrelevant. Move on. Being able to change biz logic has nothing to do with hypermedia. That's just called "good design". That's the entire point of an API: to abstract business logic and the implementation thereof from the client. Regardless, the entire idea of being able to change your API without changing the clients is just silly. If you're changing the API purely for cosmetic reasons, just stop, and learn how to be a professional. If you're changing the API's actual functionality or behavior, the code that calls the client needs to know what the new functionality or behavior is before it can make use of it, or if it's even safe to make use of it. I imagine there are some small number of cases where doing this "automatically" is actually safe, but the incidences of it are so vanishingly small that it's not worth all the extra complexity and overhead in designing and building a hypermedia API. APIs are not consumed by "smart" clients that know how to recurse a directory tree. They are consumed by humans who need to intelligently decide what API endpoints they need to use to accomplish their goals. Being able to write a dumb recursing client that is able to spit out a list of API endpoints (perhaps with documentation) is a cute trick, but... why bother when you can just post API docs on the web somwehere? This section is irrelevant given my objections to the last section. > YAML generation (default Java codegen uses annotations, codegen via this way will leak implementation details) Well, duh, don't do it that way. Do API-first design, or at least write out your YAML definition by hand after the fact. If nothing else, it's a good exercise for you to validate that the API you've designed is sane and consistent. > Swagger makes a very good first impression Yes, and for me, that impression has mostly remained intact as I continue to work with it. > What are the alternatives? Having worked with both Spring and JAX-RS, I find it hard to take someone seriously if they're strongly recommending it as a better alternative to something as fantastic as Swagger. Also note that the author previously railed on the reference impl Java tool for its reliance on annotations... which... same deal with Spring and JAX-RS.
• badreaction 10y ago
  We use swagger heavily and I can say the following: 1) We use the tolerant reader pattern. It is entirely possible to generate tolerant client code where the enum and adding new element does not cause issues. The problem here is not swagger but poor code gen. 2) We use hypermedia in all of our APIs extensively, I don't see how this is impacted by swagger? Hypermedia is a runtime discovery mechanism and so other than declaring the link structures in your schema, has no place in swagger. We don't use HAL, and wouldn't recommend it either.
  • daenney 10y ago
    Totally agree on the codegen bits. > To mitigate this problem just stop generating code and doing automatic deserialisation. Sadly, I have observed that’s a very hard habit to break. That conclusion really irks me. In Java, if you're using AutoMatter for example, you're one annotation away from discarding unknown fields and many other serialisation frameworks offer the same ability. It's not a default (which imho it should be) but it's trivial to fix.
• badreaction 10y ago
  We use swagger heavily and I can say the following: 1) We use the tolerant reader pattern. It is entirely possible to generate tolerant client code where the enum and adding new element does not cause issues. The problem here is not swagger but poor code gen. 2) We use hypermedia in all of our APIs extensively, I don't see how this is impacted by swagger? Hypermedia is a runtime discovery mechanism and so other than declaring the link structures in your schema, has no place in swagger. We don't use HAL, and wouldn't recommend it either.
• tannhaeuser 10y ago
  Why are folks using Swagger or other tools for supposedly simple REST services at all? It's not like Swagger is a "standard" or something, and from the comments it appears using tooling for REST is a zero-sum game or even net loss.
  • voycey 10y ago
    We started it using it for it's documentation and developer console generation ability at first, I have to say that I am much happier when I get given a swagger definition for an API, it lets me generate a client pretty much instantly and as long as the definition is written well it more often than not halves my integration time
    • tannhaeuser 10y ago
      I don't know if you're aware of the SOAP vs REST debate 10 years ago or Web Services vs CORBA before that. Client generation, or any code generation at all, was seen as a big no-no in the REST camp, so I find it ironic that today this is used as Swagger et. al.'s saving grace. What I frequently see is that inherently action-oriented protocols are crammed into resource-oriented REST facades, only without any formal interface descriptions at all, and without formal transactional or authorization semantics. OTOH, JSON REST services can't be used without browser-side glue code at all so the Web mismatch argument isn't working either. Makes you really wonder if there is any rationality or progress in middleware usage at all.
  • manmal 10y ago
    I was engaged in a smallish project recently where they used Swagger as a shared resource that synced server dev with mobile dev. It didn't work that well, as you can imagine.. I had to wait for the server folks to update/fix Swagger docs all the time. They also thought that they need not tell me when a breaking change occurred, because "you will see it in Swagger anyway". So I pulled changes regularly, and generated iOS code, and suddenly it broke, and then I had to hope that one of the server team is currently available for consultation.
• ogrim 10y ago
  I would never write Swagger by hand; why should I when I can have it generated? We are using Swashbuckle[0] to generate Swagger for our ASP.NET Web API, which have been a great experience. We can explore and test the API in Swagger UI. I have been sprinkling a bit of hypermedia on top of this with HAL, mainly just for having links. I have never met anyone wanting to go the full HATEOAS route, but simple links can go a long wa. Swagger UI have been great for this, as HAL alone isn't really expressive enough to document what a link means. On the consumer side, I have been using NSwag[1] to generate clients with good results. [0] https://github.com/domaindrivendev/Swashbuckle https://github.com/domaindrivendev/Swashbuckle [1] https://github.com/NSwag/NSwag https://github.com/NSwag/NSwag
  • eddieroger 10y ago
    > why should I when I can have it generated? Because maybe you work on a team where half are creating an API and half are creating a client, and if you write a Swagger spec first, you can both be working at the same time, against the same contract, and just meet in the middle? And if you're working on the consumer side of things, you can take that spec and stand it up against a mocking engine that will now give you something to test against while your API team finishes their work? Just because you would rather generate Swagger doesn't mean there's not a reason to write it by hand before writing code.
    • ogrim 10y ago
      One can still do what you are describing and have the Swagger spec generated. On my platform, I would just specify data types and the interfaces, and have Swashbuckle parse this and spit out the Swagger spec. No need to hand-code Swagger while creating the contract up front. After this step, one could work at both sides of the contract independently as you describe.
• ssijak 10y ago
  Checkout Spring REST Docs http://docs.spring.io/spring-restdocs/docs/current/reference/html5/ http://docs.spring.io/spring-restdocs/docs/current/reference... . Always uptodate docummentation, which double serves as tests, support HATOAS and more..
• andrewdb 10y ago
  I with there was a way to easily generate a swagger spec from a java project as a build artifact out of the box, instead of having to serve the spec as a dedicated API endpoint. There are some plugins, such as swagger-maven-plugin [0], that do give you this functionality, though. [0]: https://github.com/kongchen/swagger-maven-plugin https://github.com/kongchen/swagger-maven-plugin
• daliwali 10y ago
  An alternative is to just ditch these complicated documentation formats altogether. Put down your pitchforks, I'll explain. The author of REST, Roy Fielding stated that only the entry URL and media type should be necessary to know in advance. Swagger would be considered out-of-band information, if it's necessary to have this documentation beforehand then it doesn't follow this constraint. Interactions must be driven by hypermedia, an idea which has a very unmarketable acronym. The alternative that is suggested is to document media types, not APIs. If HTML were not a standard and every web page had to define its own technical specifications, the web wouldn't have taken off, because it wouldn't have been interoperable. Interoperability is key, it reduces friction from transitioning between web pages on different servers. How HTTP APIs are built today is wasteful, there are vendor-specific tooling costs up front and it doesn't scale.
  • jshen 10y ago
    What is an example of a well done API that functions the way you describe?
• hodgesrm 10y ago
  > The original problem swagger tries to solve is: API documentation. So, if you need to document an API, use a format that is created for that purpose. I highly recommend using Asciidoctor for writing documentation. There are some tools for Java that help you with this. However they are somehow technology specific. For instance Spring REST Docs works very well if you are using Spring / Spring Boot. I have used Asciidoctor + Spring REST Doc to document a complex REST API and my experience was almost complete the opposite for a number of reasons. 1.) Asciidoctor is powerful but exceedingly tedious to edit. It's especially painful to use for documenting an API in advance--wikis like Confluence are far easier to use and also allow commenting. 2.) Spring REST Doc generates snippets of asciidoc text that you must laboriously incorporate into the parent asciidoc. It's particular painful when combined with maven (another source of pain for some of us). Anybody who has asked the question "where do I look in target to find my output?" as well as "now that I found the output how do I make it go somewhere else instead?" knows what I mean. 3.) The unit tests that Spring REST Doc depends on to generate output are hard to maintain for anything beyond trivial cases. I've spent countless hours debugging obscure bugs caused by Spring IoC problems. Also, the DSL format used to define output of examples is hard to understand--just getting URLs to show https schemes and paths takes time. Finally, I would disagree that Swagger is purely designed to document existing REST interfaces. We're using it to design the interfaces in advance. It's not perfect but works better than other tools I have found let alone informal specification via a wiki. Spring REST Doc is close to useless for design.
• a_imho 10y ago
  Problems with Swagger, it is really unfortunately named. I have never used Swagger, to me it projects an aura that it is a quickly hacked weekend project its authors did not put any effort to at least name properly. Yes, I know it is irrational.
• Vinnl 10y ago
  So here's something I've never quite understood when reading about HATEOAS: > Without hypermedia, the clients would probably have to parse the payload to see if there are some kind of status and then evaluate that status to take a decision whether the order may or not be canceled. In the given example, wouldn't the client still need to check whether there actually is a `cancel` link (and know that it _can_ be there), and decide whether or not to call it? In other words, isn't it unavoidable that there's business logic in the clients?
• tomelders 10y ago
  I think Koa (or Express) are the best tools for developing an API spec/mock/doc that's useable and useful from the get go. You can have an endpoint working in seconds, and it's easy to add all the different scenarios you need. Dropping in middleware is easy too. And if you write your code well, it's self documenting. And ultimately, it's documentation for developers. I think it's as easy for a non-js dev to parse and understand an endpoint controller than it is to parse whatever freaky-deaky API documentation someone has cobbled together.
• maddening 10y ago
  To be honest I didn't knew that Swagger could generate API - still i wouldn't use anything that generates code from some description (attempts I heard of didn't worked out well in the past). In projects I worked in Swagger was used to generate callable API from existing implementation: add annotations (which are ugly :/, especially in Scala, where such javaism hurts eyes even more), generate json, open it in Swagger UI and let devs play with API. What hurt me recently was 3.0 release - basePath got broken so, I got calls generated with double slash (`host//api/call` etc.), and oauth2 is completely broken and I cannot authenticate requests. 2.0 works with no issues, though I find it sad that the vanilla version I downloaded uses hardcoded client_id and client_secret.
• epiecs 10y ago
  I also looked at swagger but found it needlessly complex for my needs. I opted for blueprint api coupled with aglio to generate html docs and also provided a nicely prepped postman collection including testing :)
• akmanocha 10y ago
  Agreed with some and not all. In essence anythung can be abused. Seagger being URI is well documented well argued problem. And no support for hypermedia too. Asciidoc and Spring Rest Docs shine there. But annotations is not IMHO. Swagger also doesny make thing more complex, they already are. Swagger also doesnt amke reading docs difficult as such *apart from URI problem above. Also Spring Rest learnt from mistakes of Swagger so its a bit unfair on swagger.
• beders 10y ago
  People often don't make a crucial distinction: Are you developing an API that happens to be accessible via HTTP or are you developing a Web Service. For an API where you control both the server and the client, you don't need to use REST. For a Web Service, where you don't control which clients are using, you are better off with a RESTful implementation supporting hypermedia. Especially if you are interested in keeping clients happy and not give them the middle-finger shaped like a incompatible-v2 version of your service.
• glukki 10y ago
  Most of developers use Swagger wrong. But this is the right approach: https://github.com/swagger-api/swagger-node/ https://github.com/swagger-api/swagger-node/ Swagger is a contract. From contract you can generate documentation, client, input/output data validation, mock responses, integration tests, and something else, I'm sure. If you start development from swagger — you can get everything in sync. That way you can't forget to update documentation, validation rules, tests, or whatever you generate from swagger. That way you can do work once! No work multiplication! It makes development So Much Easier!