5 ms·

Swagger: A simple, open standard for describing REST APIs with JSON

87 points by fogus 15y ago

stephen 15y ago
jschema and jschema-rpc both look much nicer: http://jschema.org/ http://jschema.org/ http://jschema.org/rpc.html http://jschema.org/rpc.html
- j2labs 15y ago
  jsonschema has been around for a long time too.
amalag 15y ago
I like this, but it's the third time the link has been submitted.
Radzell 15y ago
I like the name at least.
instakill 15y ago
I vehemently detest this name.
jcromartie 15y ago
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 15y ago
  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 15y ago
    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-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
    - smhinsey 15y ago
      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 15y ago
        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.
- chubot 15y ago
  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.
  - jcromartie 15y ago
    http://code.google.com/apis/gdata/ http://code.google.com/apis/gdata/ http://kenai.com/projects/suncloudapis/pages/Home http://kenai.com/projects/suncloudapis/pages/Home I don't know how successful they are.
bfrog 15y ago
I was excited until I saw it was written in Java.
- karl_freeman 15y ago
  Same, will keep looking for something similar not in Java...
  - illicium 15y ago
    Yeah. Java's, like, totally lame. /s
- fehguy 15y ago
  there is node.js... https://github.com/wordnik/swagger-node-express https://github.com/wordnik/swagger-node-express
IanDrake 15y ago
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.
ImJasonH 15y ago
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 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 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/calendar/v3/index.html http://javadoc.google-api-java-client.googlecode.com/hg/apis... * PyDoc for the Python library: http://api-python-client-doc.appspot.com/calendar/v3 http://api-python-client-doc.appspot.com/calendar/v3
- fehguy 15y ago
  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 15y ago
Not a new idea, but it seems a pretty implementation. I've played with Spore a little in the past: https://github.com/spore https://github.com/spore Client implementations include: - Perl: https://github.com/franckcuny/net-http-spore https://github.com/franckcuny/net-http-spore - JS (Node): https://github.com/francois2metz/node-spore https://github.com/francois2metz/node-spore - Lua: https://github.com/fperrad/lua-Spore https://github.com/fperrad/lua-Spore - Ruby: https://github.com/sukria/Ruby-Spore https://github.com/sukria/Ruby-Spore - Clojure: https://github.com/ngrunwald/clj-spore https://github.com/ngrunwald/clj-spore
johnmw 15y ago
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 15y ago
  Usergrid ( https://apigee.com/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 15y ago
I'll just leave this here in case anyone still cares... http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...
Feeble 15y ago
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-rest-api-with-enunciate/ 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?
- fehguy 15y ago
  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 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.

87 points by fogus 15y ago

jschema and jschema-rpc both look much nicer: http://jschema.org/ http://jschema.org/ http://jschema.org/rpc.html http://jschema.org/rpc.html

j2labs 15y ago
jsonschema has been around for a long time too.

amalag 15y ago

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

Radzell 15y ago

I like the name at least.

instakill 15y ago

I vehemently detest this name.

jcromartie 15y ago

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 15y ago
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 15y ago
  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-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
  - smhinsey 15y ago
    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 15y ago
      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.
chubot 15y ago
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.
- jcromartie 15y ago
  http://code.google.com/apis/gdata/ http://code.google.com/apis/gdata/ http://kenai.com/projects/suncloudapis/pages/Home http://kenai.com/projects/suncloudapis/pages/Home I don't know how successful they are.

bfrog 15y ago

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

karl_freeman 15y ago
Same, will keep looking for something similar not in Java...
- illicium 15y ago
  Yeah. Java's, like, totally lame. /s
fehguy 15y ago
there is node.js... https://github.com/wordnik/swagger-node-express https://github.com/wordnik/swagger-node-express

IanDrake 15y ago

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.

ImJasonH 15y ago

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 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 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/calendar/v3/index.html http://javadoc.google-api-java-client.googlecode.com/hg/apis... * PyDoc for the Python library: http://api-python-client-doc.appspot.com/calendar/v3 http://api-python-client-doc.appspot.com/calendar/v3

fehguy 15y ago
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 15y ago

Not a new idea, but it seems a pretty implementation. I've played with Spore a little in the past: https://github.com/spore https://github.com/spore Client implementations include: - Perl: https://github.com/franckcuny/net-http-spore https://github.com/franckcuny/net-http-spore - JS (Node): https://github.com/francois2metz/node-spore https://github.com/francois2metz/node-spore - Lua: https://github.com/fperrad/lua-Spore https://github.com/fperrad/lua-Spore - Ruby: https://github.com/sukria/Ruby-Spore https://github.com/sukria/Ruby-Spore - Clojure: https://github.com/ngrunwald/clj-spore https://github.com/ngrunwald/clj-spore

johnmw 15y ago

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 15y ago
Usergrid ( https://apigee.com/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 15y ago

I'll just leave this here in case anyone still cares... http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...

Feeble 15y ago

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-rest-api-with-enunciate/ 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?

fehguy 15y ago
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 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.