
Swagger: A simple, open standard for describing REST APIs with JSON - fogus
http://swagger.wordnik.com/
======
jcromartie
The 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.

~~~
coolgeek
Just so that I'm clear on this, are you just criticizing that all requests go
to /word.json?

IOW, would the following be RESTful?

GET /entries/{word} # Return entries for a word

GET /wordForms/{word} # Rturn other forms for a word

POST /wordForms/{word} # Adds a relationship map for a word

~~~
arethuza
I think the point is that if you are documenting the structure of URIs you are
focusing on the wrong thing - a RESTful interface documentation should mostly
be about the hypermedia (HTML, XML, JSON,...) that the URIs are embedded in -
a particular server should really have the freedom to construct the URIs in
any way it wants and still have clients that understand the API work.

See: [http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

~~~
smhinsey
I think when done right (a subjective measurement, to be sure) the only URI
you care about for a RESTful API is the root, because the API's resources are
defined, along with how they can be manipulated, in the root response or can
be transitioned to from there in some way that is defined there.

~~~
jcromartie
Yes, that's the key. If the media types are documented (like how browsers and
developers understand HTML forms) then you don't need to document every single
corner of the API. You can offer a good definition of the media types, and let
the resources and links do the rest.

------
ImJasonH
This 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/hg/apis...](http://javadoc.google-api-java-client.googlecode.com/hg/apis/calendar/v3/index.html)

* PyDoc for the Python library: <http://api-python-client-doc.appspot.com/calendar/v3>

~~~
fehguy
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.

------
MattJ100
Not a new idea, but it seems a pretty implementation. I've played with Spore a
little in the past: <https://github.com/spore>

Client implementations include:

\- Perl: <https://github.com/franckcuny/net-http-spore>

\- JS (Node): <https://github.com/francois2metz/node-spore>

\- Lua: <https://github.com/fperrad/lua-Spore>

\- Ruby: <https://github.com/sukria/Ruby-Spore>

\- Clojure: <https://github.com/ngrunwald/clj-spore>

------
IanDrake
While documentation is good, I still don't get the need for programmatic
documentation.

I suppose the desire is to have a service describing itself so proxies can be
code gen'd, but I'm glad I've stepped away from that world and don't miss the
WSDL days.

------
stephen
jschema and jschema-rpc both look much nicer:

<http://jschema.org/>

<http://jschema.org/rpc.html>

~~~
j2labs
jsonschema has been around for a long time too.

------
Feeble
I 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...](http://www.sonatype.com/people/2010/02/documenting-the-nexus-rest-
api-with-enunciate/)). 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?

~~~
fehguy
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.

------
instakill
I vehemently detest this name.

------
johnmw
Does anyone know of a tool that can take a API type schema and can actually
generate the API for you?

I'm talking about a simple CRUD type APIs for quick development. Ideally it
would have user sign up and simple field validation baked in.

~~~
earth2marsh
Usergrid ( <https://apigee.com/usergrid> ) addresses at least some of what
you're looking for. If you try it, let me know, as I'm part of that team
that's working on it.

------
epe
I'll just leave this here in case anyone still cares...

[http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

------
Radzell
I like the name at least.

------
bfrog
I was excited until I saw it was written in Java.

~~~
karl_freeman
Same, will keep looking for something similar not in Java...

~~~
illicium
Yeah. Java's, like, totally lame.

/s

------
amalag
I like this, but it's the third time the link has been submitted.

