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)
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?
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 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.
There's nothing complicated about a client that understands Hypermedia links. You start at the root, it'll give you a set of links to follow, and you recurse. Here's a browser that can take a HATEOAS-compatible API and will let you work your way through the API: http://dracoblue.github.io/hateoas-browser/
> Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort.
Correct. HATEOAS is a neat parlor trick: point a dumb client at your API and watch it enumerate all the possible operations. Wow! The problem is that APIs aren't consumed that way, they're consumed by humans who need to decide which API calls to make based on user actions in the application... so developers will resort to consulting documentation in order to piece together the correct calls in the correct order. That's not something you can encode through Hypermedia. At best you can just model the relations between calls, but not the "how" or "why" of everything.
Fundamentally, your display logic should not be linked to your API schema, but HATEOAS essentially enforces that, because you can't predict what links will be available.
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
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 There are many others as well (especially for the HAL format).
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
you get some html with embedded links and then the browser automatically goes and fetches css, js, images...
the remaining links it just presents to you, the user, to follow or not as you choose
hateoas is not a complicated idea. it's not meant to replace SOAP or gRPC or thrift. it's something else
The HATEOAS idea is that you throw that out, just use some aribitrary XML (sorry, "hypermedia") to return your application state, and that this somehow magically empowers the client to be able to puzzle out all the things that can be done to your state.
Except it can't. It's just arbitrary junk if you don't have a schema and a spec. And it will always be so. Discoverability is (1) not something you can get from a data structure and (2) something best provided by documentation, not runtime behavior.
I think REST/HATEOAS purists have always overplayed the browser example.
Pure machine to machine interaction is hard to automate.
It depends, it's just a way to reduce coupling between a webservice and its client apps. Instead of hardcoding all the URL endpoints into the client, the client has to follow the links provided by the webservice instead. If this layer of indirection has advantages for you depends on your use case. You could compare it to using DNS instead of static IPs. Static IPs work fine but you end up with more coupling than using DNS.
a) know how to retrieve that link (i.e. what resource do I need to retrieve in order to get that response)
b) requirement for that link to exist (they still need that link).
Requiring that a client know that to get data Bar, they need to retrieve resource A, follow the link at foo[n]._link to retrieve resource B, and then following the link at _link.bar feels like a total non starter, and actually increases coupling.
I have a really hard time seeing APIs ever reaching that level of standardization, and I'm tired of having the Hypermedia discussion. I generally support logically organized APIs with good documentation. As long as those things are true, I'm happy for the API.
REST if your API should not maintain state between requests. If you want links as a part of your response (and want to use a standard) use e.g. HAL or JSON API.
I view them as mutually exclusive.
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.
I've never really liked the REST paradigm, so I'd be pleased to see it die.
My biggest complaint with Thrift: they still make you do some convoluted hacks to get a two-way ("streaming") connection in the RPC, and when this is discussed, they usually kibosh it pretty quickly by saying it's an unsupported case and that you can find some hacks online, but they don't want to talk about it any further.
This may not have been a big problem for them before gRPC was released for protobufs, but it's definitely something that's worthy of attention and response now. I know lots of people who are going with protobufs instead because of this.
The other thing is that while Thrift boasts a lot of language compatibility, several of these are buggy.
Don't hold your breath. Fielding's thesis is already 17 years old, so one would expect its philosophy to endure by the Lindy Effect if for no other reason.
There are lots of things in tech that we just stop doing one day. They get replaced by a different hot new thing. I'm sure REST will not go extinct for a very long time, but it definitely could go cold, just like its popular predecessors.
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.
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.
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).
Check it out yourself: 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.
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 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-...
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) or https://generator.swagger.io (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)
We wanted to produce named enumerables by using custom extensions and found no way of doing it with Mustache. It didn't help that our custom extension YAML was passed into Mustache as serialized JSON. One of our developers took it upon himself to make it work and ended up writing his own simple version of the Codegen which works well enough for us. He tried modifying one of the backends preparing data for Mustache but then said rewriting it on his own was just simpler.
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.
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.
[0] https://github.com/domaindrivendev/Swashbuckle [1] https://github.com/NSwag/NSwag
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.
> 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.
XML is indeed for machines, that is, the markup part of it. YAML may be more readable, but note that the specification of YAML is about three times as large as that of XML (and the XML specification also describes DTDs, a simple grammar specification language). XML design goals are explicitly stated in its specification, you're free to take a look.
* use a decent editor to write the YAML e.g. 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 (Python API-first) * follow best practices and guidelines to have a consistent API experience, e.g. 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.
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.
> 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.
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.
Defining a DSL is almost alway a better idea (but more difficult) than defining a configuration format.
I mean the essential difference. ;-)
Edit: Cheers to you guys at Novatec, have to take a look on InspectIT again.
Export your file frequently.
> 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.
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
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>.
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.
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.
Here's a renderer: https://github.com/danielgtaylor/aglio
It's less feature-rich than Swagger but the format is much less of a nightmare.
> 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?
(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
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) and embed it in our Slate documentation using our Slate documentation generator. (https://github.com/buremba/swagger-slate)
Here is an example: http://api.rakam.io/
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.
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.
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.
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!
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.
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.
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.
