10 ms·
Swagger is now the OpenAPI Specification
- rvanmil 9y agoDon't be fooled kids, this may sound great but it is in fact the gate to hell. Back when I was young the same thing was called SOAP and it also promised standardized APIs in a vendor neutral description format and code generation. It was pure misery. I still have nightmares about it. They may say they only bring the good parts of SOAP, but there are no good parts in SOAP.
- xr4ti 9y agoHi! Can you detail some of the problems you have with SOAP? I'm superficially familiar with Swagger, but probably below the level of dilettante when it comes knowing about SOAs in general.
- hmschreck 9y agoSOAP has a lot of really awful implementations in it, and there's much less standardization and a lot more "spaghetti meeting wall" APIs in SOAP than I've seen using standard REST APIs.
- mythz 9y agoMany years ago I wrote about some of the issues with WCF/SOAP at: https://www.infoq.com/articles/interview-servicestack https://www.infoq.com/articles/interview-servicestack
- danvasquez29 9y agoI'm in the middle of getting rid of the last SOAP dependency for my app now. might throw a little party when it's done.
- wwosik 9y agoIt will be different this time (tm) But in all seriousness, while I dont believe much in code generation and super smart generic client, a common platform for describing rest apis is more useful than reinventing the wheel for every new service or rather worse - a Word document on Sharepoint with endpoint description.
- duskwuff 9y agoThe 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.
- 9y ago
- deckar01 9y agoSOAP is a nightmare, but my experience with Swagger has not been so far. I used flask and marshmallow to create an API and a plug-in to generate the swagger scheme from it. It just worked. I see it more as an interactive documentation generator than some kind of dynamic API pipe dream.
- michaelsbradley 9y agoI was recently tasked with tightening up and documenting an HTTP API I didn't write. The original authors used Django and Django REST Framework[1], but lacking deep experience with either, mostly rolled their own functions for requests, responses, and communications with the back-end databases and other external data sources. Rather than attempting to sort it out, I used Paw[2] to get my arms around the API from a consumer's POV, had Paw generate a skeleton of an OpenAPI 2.0 (Swagger 2.0)[3] description, converted it to YAML[4] and began putting flesh on the bones manually (yaml-mode[5] in Emacs is pretty decent). In the process of covering all the bases with precise req/res definitions and examples (yay, JSON Schema![6]), I uncovered a lot of corner cases in the API's functionality and made sure they were handled properly or at least documented well. I co-located the openapi.yaml file and ReDoc[7] with the API, and now it has beautiful web-based documentation. It also has JS, Python and curl code samples for all endpoints, generated with Paw and included in the YAML formatted description. ReDoc displays them nicely, with syntax highlighting. In short, even though I worked "backwards" — matching the OpenAPI description to the functionality — it was a fruitful exercise and the results seem pretty good. Not to mention, all the above is readily tracked with git and can live right next to the server's source code... compared to, say, an equivalent documentation effort accomplished with MS Word. [1] http://www.django-rest-framework.org/ http://www.django-rest-framework.org/ [2] https://paw.cloud/client https://paw.cloud/client [3] https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md https://github.com/OAI/OpenAPI-Specification/blob/master/ver... [4] http://www.yaml.org/ http://www.yaml.org/ [5] https://github.com/yoshiki/yaml-mode https://github.com/yoshiki/yaml-mode [6] http://json-schema.org/ http://json-schema.org/ [7] https://github.com/Rebilly/ReDoc/ https://github.com/Rebilly/ReDoc/
- dreamfactored 9y ago
- ff_ 9y agoWhat's "bad" in: 1. Having strong and documented boundaries at API level 2. Being able to generate clients from a server spec, so I don't have to write interop code anymore. 3. Being able to generate server client from a design document (the spec) - I did it just last week, and it works magically. Should I do it by hand? Swagger is bad only if you use it wrong, like it's the case with SOAP, Java, and other things which have good parts but have been misused so many times people got pissed of them.
- bernadus_edwin 9y agoI try swaggerbuckle nuget c#. It was easy to consume from ios swift. Then i try on android. Not easy. Then try again on react native js, also not easy. My suggestion is try one or two simple API.
- fizx 9y agoSOAP is a shitty implementation of a perfectly good idea. GRPC, for example, is a vast improvement over JSON+REST. YMMV with Swagger, as I've never tried it.
- mmsmatt 9y agoGRPC is fantastic. You define a few data types to communicate about, and call procedures remotely with them. I mean it’s right there in the name! Unfortunately it doesn’t come with a Methodology you can cram your business or research problem into. It just wants to talk about your problem. Way too on-the-nose for many tastes. It needs a religion attached, then masses will follow.
- ralmeida 9y agoWhat do you suggest using for API documentation? Genuinely curious.
- sb8244 9y agoI'm going to answer this despite not being the parent. I've looked into this problem area 2 years apart now. The first time I came across swagger 2 and some Ruby toolings to automatically turn source code annotations (not comments) into my api docs. I was hoping to not do this 2 years later so really looked hard into it. I was dismayed to find that all of the good looking out of the box tools required writing docs by hand, no generation! I looked back into swagger 2 and found great success this time around. A few things were important: 1. Building the API how I wanted which involved integrating docs into the actual functionality. For instance, all params and response attributes are defined in the code and then turned into documentation later. 2. Spending time to get the docs how we wanted them, not just going with the stock. 3. Not being afraid to break the spec with custom json descriptions when necessary. Not pretty but entirely functional. We do not use swagger for auto generation or testing, only documentation. I do not think that the current swagger UI implementation is attractive and think they're missing hard by not spending more time on the design style that is trending now. The spec itself is solid. I'm going to promote the blog post I wrote about it. Feel free to not read it if you're not into self promotion. https://medium.com/salesloft-engineering/building-the-new-salesloft-api-99660c13b539 https://medium.com/salesloft-engineering/building-the-new-sa...
- fineline 9y agoAhh the good old days. I can't hear SOAP without thinking this video: https://www.youtube.com/watch?v=Mhllo1xQer8 https://www.youtube.com/watch?v=Mhllo1xQer8 in particular 1:45 to 2:00.
- derefr 9y agoI used a service once, just recently, whose API was SOAP (I think it was the one for VoIP.ms?) Instead of documenting their API, they gave me a WSDL file to download and told me to plug it into any WSDL-supporting SOAP client. So I threw it into http://fagiani.github.io/savon/ http://fagiani.github.io/savon/ in a Pry session, got back an object representing the API gateway, and then just... started exploring the API using it and Pry, treating the objects and their properties the way I would those of a regular Ruby library. It was honestly a nice experience, and it would have been even nicer if I had to deal with more than one API, because I could have just kept dealing with Savon rather than finding a new (maybe not-very-well-written) client library for each new service. So, I don't get the hate for SOAP/WSDL. Is it the process of building the SOAP service that's frustrating? The process of creating the WSDL document? I didn't have to deal with either of these, so maybe that's where the hatred boils up from. Was it integrating code-generation into the build process? Again, since I was using a dynamic language (Ruby) whose SOAP library (Savon) parsed WSDL and built up its client-proxies in memory at runtime, I didn't have to deal with this. Or was it dealing with brittleness and edge-cases and a lack of fidelity in the types you could pass through such APIs? I didn't have a problem with this personally, but I might have just been dealing with a uniquely-well-architected backend service.
- Arnavion 9y ago>So, I don't get the hate for SOAP/WSDL. AFAIK one of the sources of hatred for SOAP is people building the message bodies by hand using browser JS instead of using a code generator (one might not have existed for browser JS at that time). Not only was it complicated by being XML, but SOAP bodies are especially verbose XML.
- dreamfactored 9y agolack of cacheability is the main issue I've heard
- jbergstroem 9y agoIt's usually extra hostile for things like caching. I've (on multiple occasions) seen one URI endpoint, http posts and method as a separate header. Pretty much as far away from a sane caching best practice as you can go. Also; a lot of these older web services doesn't support deflate, gzip (accept-encoding, vary, ..) so your average responses are 500kb and up. :'( In a recent project, a client saturated their wire as a result of just this.
- svanwaa 9y ago"It was pure misery" - Give CORBA a try sometime. :)
- sb8244 9y agoSOAP and swagger are entirely different things. I'm sorry you had a bad experience, but it seems like you're making a strong negative claim with only anecdotal evidence. I am curious if there are concrete examples though.
- stuaxo 9y agoI had a nightmare time on J2me with SOAP and Samsung phones. The generated wrapper was sometimes triggering a bug that would crash the phone. The generated code was a byzantine mess. The bug didn't trigger anything catchable in the code. This wasn't even the worst thing in that project, but may have been the straw that broke the camels back.
- beefsack 9y agoSOAP defines your API, OpenAPI just describes it. We wrote an OpenAPI spec for our existing API and just use it to generate documentation for external parties and it's worlds ahead of what we used to do.
- slaymaker1907 9y agoSwaggerUI is awesome enough to justify the complexity.
- pkamb 9y agoThe one Swagger docs site my team used, we all thought it was completely broken for the first several weeks of trying to access it. Turns out there was a small red ("error" colored...) header bar near the top, collapsed by default. You need to click that to expand out all the API docs. Fun design.
- anon335dtzbvc 9y agoStill the best option is the unix philosophy: "Write programs to handle text streams, because that is a universal interface." - Peter H. Salus in A Quarter-Century of Unix (1994)
- deathanatos 9y agoIt really isn't the universal interface. At some point, most of us need to transfer more than just "text", even if we end up representing the data as text. For example, if I need to describe the name, breed, and sex of a set of dogs, I can transfer that as JSON: [ { "name": "Spot", "breed": "Dalmatian", "sex": "male", }, ... ] as CSV: name,breed,sex Spot,Dalmatian,male etc. The list goes on. The concept of "text" fails to capture both the higher-lever format (JSON, CSV) and the lower-level details (what the keys are in JSON, what values might be valid for enumerations such as "sex", etc.; what units for numeric types, how do we represent null (esp in CSV), etc.). For JSON HTTP APIs, Swagger makes a not-that-bad (IMO) attempt at describing the format of the structure. The Unix philosophy, while it works well in specific cases, does not lend itself well to the creation of robot solutions. Parsing text streams with tools like sed/grep which are not the right tool for the job, in that they cannot understand the corner-cases of JSON/CSV/etc., leads to brittle solutions. (e.g., a use of sed/awk on the above CSV might work, until we get a more complicated format in a later iteration with a field containing an embedded newline, and our awk script falls down b/c we're not using a real CSV parser.)
- vonseel 9y agoIsn’t any HTTP API technically a program to handle a text stream? This comment is overgeneralizing.
- kbp 9y agoThat quote is actually by Doug McIlroy, who also gave this longer phrasing of it: "Expect the output of every program to become the input to another, as yet unknown, program. Don't clutter output with extraneous information. Avoid stringently columnar or binary input formats. Don't insist on interactive input."
- Kpourdeilami 9y agoAnother API specification that I really like is [CoreAPI](http://www.coreapi.org/ http://www.coreapi.org/) . It works nicely with the django-rest-framework (both created by the same person) and has clients for python, javascript, and a command line tool to interact with the API. I have written a small python script that takes our CoreAPI specification and then generates markdown documentation around it. The catch is that it is not as well documented as Swagger so working with it would require digging into its source code.
- patkai 9y agoIs there a good writeup on "WSDL: Lessons learned", with some depth?
- OJFord 9y agoI'm very confused, the article bills this as news, but this has been true for at least a year, is the news that v3 is now 'current' rather than in development? https://github.com/OAI/OpenAPI-Specification https://github.com/OAI/OpenAPI-Specification
- sb8244 9y agoI believe you're correct. It hasn't been official yet despite being mostly ready to go
- tschellenbach 9y agoI don't see how Swagger helps me build, document or test my API. Anyone have a good experience to share?
- zamalek 9y agoSo far as documentation goes, OpenAPI does include fields for human consumption - such as "example". I've been using Swaggerhub to validate my OpenAPI documents and it clearly demonstrates what the automatically-generated documentation might look like. It won't help you at all with unit testing (you shouldn't be using HTTP for that). You can theoretically use it to generate a client library in your language of choice for integration tests (true for Swagger, not yet for OpenAPI). Finally, there are tools built around it that let you play around with APIs that have these specs - Microsoft PowerBI comes to mind. There are ways you could use it to build an API, but I wouldn't consider them a good idea. Edit: You could completely automate the process of ensuring that your semantic versions are compliant (i.e. you aren't breaking compatibility when you are claiming that you are not).
- deleted 9y ago[deleted]
- jimmcslim 9y agoDo Swagger/OpenAPI and its more popular implementations support JWT/bearer tokens yet?
- quicklyfrozen 9y agoThe spec seems to: https://swagger.io/docs/specification/authentication/bearer-authentication/ https://swagger.io/docs/specification/authentication/bearer-... I'd be curious about implementation support as well. I was able to get it to work with earlier versions, but IIRC it involved using the apiKey in header auth type and manually adding "Bearer" to the auth header.
- czardoz 9y agoI always found Swagger to not be very readable or usable. APIs keep changing, and are meant to be malleable, not rigid. IMO, Swagger always ends up being too much planning, too little implementation. I remember having a bunch of discussions about these issues when I worked on the Postman Collection Format (https://github.com/postmanlabs/postman-collection/blob/develop/examples/collection-v2.json https://github.com/postmanlabs/postman-collection/blob/devel...) which can be very flexible.
- pixie_ 9y agoIs there any standard as to how to do some of these thing - API versioning? actions like login/logout? doing a GET on multiple IDs? spinal casing? common response object format? application specific error codes?
- quicklyfrozen 9y agoThe spec allows you to describe how you decide to implement these things; it doesn't proscribe any particular API patterns. You can declare types separately from APIs to make your last two items easier.
- mhw 9y agoJSON API covers some of that: http://jsonapi.org http://jsonapi.org
- michaelbryzek 9y agoAPI Builder [https://www.apibuilder.io https://www.apibuilder.io] integrates many of the end to end tools teams need to manage APIs at scale. JSON remains first class and support for swagger is native (also supports avro idl… protobufs to come). API Builder was started in 2014 as a free and open source project to build a community around best practices we learned scaling gilt.com and building flow.io. Managing great APIs end to end at scale and over time take a huge investment in culture and tooling. API Builder solves a number of those problems. A few reasons why teams adopt API Builder. - Very, very high quality generated clients: Teams that use API Builder end up relying 100% on the generated clients - ie. the developers STOP writing and managing their own client SDKs, freeing up time to focus on product improvements. - History: Every change in spec is documented - accurate and automatic - e.g. https://app.apibuilder.io/history?org=apicollective&app=apibuilder-spec https://app.apibuilder.io/history?org=apicollective&app=apib... - Resource centric: API Builder is resource first - instead of defining an operation explicitly, you define resources and then expose operations on that resource. - Simple service specification: API Builder at its core separates the notion of the input format (e.g. api.json, swagger, avro) from the service description (service.json). This is a huge advantage: regardless of input format, the service specification can be fully expanded and complete. - Simple input format: The default api.json format is simple for humans to write. It is JSON, but more than that it is approachable by a novice and designed to be both simple and easy. - Easy to add code generators: Code generators in API Builder are themselves REST services which accept a service description (in JSON) and essentially return a string. Teams often write their own code generators - even small disposable ones - to systematically solve problems in an automated fashion. - Testability of clients: With generated mock clients built from the same interface definition, teams can rely on mocks when building automated tests - and further use the provided mock clients to override only the specific features needed for a given test. - Workflow that works with micro or mono repos and allows for concurrent, branched development of spec, service and client More at https://www.apibuilder.io/ https://www.apibuilder.io/ and https://app.apibuilder.io/doc/why https://app.apibuilder.io/doc/why [edit: formatting]
- pritambarhate 9y agoWhich editor do you use to edit Swagger? Writing Swagger specification by hand is a nightmare because of the poor online editor. The error messages are hard to understand. Also Swagger.io people decided to replace the old editor with the new editor and it doesn't have many useful features the old has. Thankfully they kept the old one live. Swagger is not all that hard to understand. This is a fantastic tutorial which helped a lot to get started: https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/ https://apihandyman.io/writing-openapi-swagger-specification...