4 ms·
The Swagger/OpenAPI spec format is its own special little hell. Just enough "user friendly" features to make it difficult to parse, yet still complicated enough
by duskwuff 9y ago
The Swagger/OpenAPI spec format is its own special little hell. Just enough "user friendly" features to make it difficult to parse, yet still complicated enough that it's a pain to write.
- hobofan 9y agoI thought I was the only one! As far as I can tell the sentiment regarding Swagger/OpenAPI is generally positive, but I am starting to think that's just because it's an improvement over the status quo of "nothing" for most people. I personally prefer API Blueprint, but even there is room for improvement.
- thejosh 9y agoMaybe it's because the only APIs I've dealt with are kind of terrible, leads a bad taste in my mouth.
- bjz_ 9y agoI prefer RAML tbh - using Markdown as the basis of an API specification language is a pretty terrible idea. RAML's syntax is much more structured and pleasant, and the type syntax is far nicer to write than JSON Schema. Alas it seems to have lost the battle of network effects...
- AdeptusAquinas 9y agoI would assume most people would use an extension to generate swagger off their endpoints on demand. Thats what I do in ASP.NET, via a library called Swashbuckle: Swagger and Swagger UI in three lines of code.
- mmsmatt 9y agoSOAP, WCF, CXF, et al, what’s old is new again. It’s strange to have been playing this game long enough to see a full cycle. Here be dragons.
- AdeptusAquinas 9y agoBiggest difference continues to be the complexity of the client required. For HTTP webservices, its still a massive step forward.
- avita1 9y agoWhat does the complexity matter? Either way you're running some service description file through some build tooling to generate some human unfriendly code. Who cares how big or complex the code in the middle is?
- AdeptusAquinas 9y agoBecause in most cases that I have experienced, no, you are not running the sdl through a generator to create a client. You are instead instantiating a http client, setting the right headers, urls, package bodies etc, all by hand. Something which is done in lieu of using a code generator because its trivial with an HTTP web service. Furthermore, with an http api and depending on your security model, you can test/inspect a good portion of your APIs directly with a browser - a zero-cost client for all http apis that you get for free.
- pjmlp 9y agoThat is what tools like SoapUI are for.
- brango 9y agoYou're not meant to write it by hand. I know you can, but why would you want that world of pain?
- metachris 9y agoSwagger is typically used to auto-generate nice and interactive API docs automatically, not really meant to be written by hand.
- dtech 9y agoI have never felt the need to write swagger by hand, despite publishing a few API's in it. I always generate them directly from the domain code/function arguments. It might be a benefit of statically typed languages though. I have no idea how you would automatically generate swagger from Javascript, without adding so much annotations that they become a poor man's types.
- pishpash 9y agoAh, the quixotic quest to square the circle, or in this case, design a language in which you can describe everything and yet everything is succinct.
- api 9y agoORMs and RPC / self-documenting API standards are like the Korean and Vietnam wars of programming.