News for hackers. Stuff that matters.
Re:Swagger is now the OpenAPI Specification by duskwuff on Monday October 23, 2017 @01:56PM (#15535323)
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.
Re:Swagger is now the OpenAPI Specification by hobofan on Monday October 23, 2017 @02:04PM (#15535400)
I 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.

Re:Swagger is now the OpenAPI Specification by bjz_ on Monday October 23, 2017 @09:06PM (#15538360)
I 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...
Re:Swagger is now the OpenAPI Specification by thejosh on Monday October 23, 2017 @03:02PM (#15535983)
Maybe it's because the only APIs I've dealt with are kind of terrible, leads a bad taste in my mouth.
Re:Swagger is now the OpenAPI Specification by AdeptusAquinas on Monday October 23, 2017 @02:07PM (#15535427)
I 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.
Re:Swagger is now the OpenAPI Specification by mmsmatt on Monday October 23, 2017 @03:10PM (#15536042)
SOAP, 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.

Re:Swagger is now the OpenAPI Specification by AdeptusAquinas on Monday October 23, 2017 @03:44PM (#15536337)
Biggest difference continues to be the complexity of the client required. For HTTP webservices, its still a massive step forward.
Re:Swagger is now the OpenAPI Specification by avita1 on Monday October 23, 2017 @04:45PM (#15536796)
What 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?
Re:Swagger is now the OpenAPI Specification by AdeptusAquinas on Monday October 23, 2017 @05:45PM (#15537186)
Because 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.

Re:Swagger is now the OpenAPI Specification by pjmlp on Tuesday October 24, 2017 @03:29AM (#15539845)
That is what tools like SoapUI are for.
Re:Swagger is now the OpenAPI Specification by pishpash on Monday October 23, 2017 @03:59PM (#15536455)
Ah, 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.
Re:Swagger is now the OpenAPI Specification by api on Monday October 23, 2017 @05:58PM (#15537284)
ORMs and RPC / self-documenting API standards are like the Korean and Vietnam wars of programming.
Re:Swagger is now the OpenAPI Specification by brango on Monday October 23, 2017 @02:23PM (#15535578)
You're not meant to write it by hand. I know you can, but why would you want that world of pain?
Re:Swagger is now the OpenAPI Specification by dtech on Monday October 23, 2017 @03:09PM (#15536030)
I 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.

Re:Swagger is now the OpenAPI Specification by metachris on Monday October 23, 2017 @02:55PM (#15535911)
Swagger is typically used to auto-generate nice and interactive API docs automatically, not really meant to be written by hand.