I was excited until I saw it was written in Java.
Same, will keep looking for something similar not in Java...
Yeah. Java's, like, totally lame.
/s
Swagger: A simple, open standard for describing REST APIs with JSON
21–26 of 26 posts
Re: Swagger: A simple, open standard for describing REST APIs with JSON
#22This is similar in spirit to the Google APIs Discovery Service, an API to describe recent Google APIs. http://code.google.com/apis/discovery/v1/using.html This is used to power the APIs Explorer, and code/documentation generation for client libraries: * APIs Explorer: https://code.google.com/apis/explorer * JavaDoc for the generated Java library for Calendar API: http://javadoc.google-api-java-client.googlecode.com/h…
I think the biggest difference is that this is a framework, not just a spec, and you can implement the server with the libraries. The google explorer makes it easy to consume google apis, which is great if that's what you're trying to do. If you want others to consume your api, you need a framework to facilitate the schema generation.
Re: Swagger: A simple, open standard for describing REST APIs with JSON
#23The example demonstrates an RPC-style HTTP API with pretty URLs. There's no hypermedia in sight. Oh well, we'll figure it out one day... That being said, this is exactly the sort of documentation that's helpful for this kind of API.
That's the theory... but the gaping hole is that JSON doesn't define hyperlinks like HTML does. Also, I think Subversion tried to make resources discoverable from the root with WebDAV, but it just leads to crazy latency with all the round trips, and everyone agrees it was a mistake.
Any APIs you can point to that actually use "hypermedia" and are successful? Most good APIs I've seen just define a bunch of simple JSON endpoints with predictable URLs.
Re: Swagger: A simple, open standard for describing REST APIs with JSON
#24The example demonstrates an RPC-style HTTP API with pretty URLs. There's no hypermedia in sight. Oh well, we'll figure it out one day... That being said, this is exactly the sort of documentation that's helpful for this kind of API.
That's the theory... but the gaping hole is that JSON doesn't define hyperlinks like HTML does. Also, I think Subversion tried to make resources discoverable from the root with WebDAV, but it just leads to crazy latency with all the round trips, and everyone agrees it was a mistake. Any APIs you can point to that actually use "hypermedia" and are successful? Most good APIs I've seen just define a bunch of simple JSON…
http://code.google.com/apis/gdata/
http://kenai.com/projects/suncloudapis/pages/Home
I don't know how successful they are.
Re: Swagger: A simple, open standard for describing REST APIs with JSON
#25I think this is a really good idea. So far I have been using Enunciate to do exactly this (http://www.sonatype.com/people/2010/02/documenting-the-nexus...). I have been happy with Enunciate so far but they seem to have lost traction and their API does not work with Java 7 for instance. Swagger looks a bit cooler too ;)
That being said, there are some thing that they do that Swagger seems to be missing (or I am just missing it). For instance Enunciate does not require any custom annotations but uses the normal Javadoc instead, which is a very good feature. And how do I run Swagger, can I plug this into my Maven build process and include in the generated war file?
Re: Swagger: A simple, open standard for describing REST APIs with JSON
#26I think this is a really good idea. So far I have been using Enunciate to do exactly this ( http://www.sonatype.com/people/2010/02/documenting-the-nexus... ). I have been happy with Enunciate so far but they seem to have lost traction and their API does not work with Java 7 for instance. Swagger looks a bit cooler too ;) That being said, there are some thing that they do that Swagger seems to be missing (or I am just…
We tried out enunciate as well. It's good but didn't quite fit our needs...
You can run swagger with the built-in support via swagger-core/swagger-jaxrs. Play 1.4/2.0 support is there as well and a number of folks are creating support for other server frameworks. See the samples for integration:
https://github.com/wordnik/swagger-core/tree/master/samples
But to be honest, you can run the whole system with static files and zero server integration.
The downside of using javadocs is that you need to expose sourcecode/docs.