Swagger-core 1.2 released! Here’s what it means for you

When we first architected Swagger, the goal was to programmatically describe our APIs with the purpose of keeping our documentation always up-to-date. The specification grew in importance internally, and helped us auto-generate a sandbox UI, client SDKs, server skeletons, and even document legacy APIs.

Now about 15 months after being open-sourced, we have integrated support across nearly all popular server languages, including PHP, Python, Java, Scala, Ruby, and JavaScript. Swagger is right in the middle of huge API infrastructures such as Klout and IGN, and is helping make tools for developer-focused SDKs from the likes of Singly and the 3Scale API management platform.

We’ve received a ton of feedback and contributions to both our framework and the specification from bright and ambitious developers around the world. It’s been a great experience!

Today we are announcing swagger-core 1.2 which facilitates a key request – the integration of the resource and API listings with the server framework. Here is a brief background.

Swagger supports a Resource Listing – that is, an inventory of all APIs on a particular system – similar to a site map for the API. The resource listing contains pointers to API Declarations, which are used to describe the actual API functionality and the models either produced or consumed.

The original resource listing was auto-generated by the Swagger framework under the path `resources.{format}` (where {format} is either .xml or .json). The framework also encouraged placing the API Descriptions under the *root* of each API path. So /pet.json would contain the API Description for the Pet API, etc. The problem is, many people already have dedicated uses for the root resource on their APIs.

With that in mind, we’ve changed the default behavior of the swagger-core framework to produce the Resource Listing and API Descriptions as follows:

  • The Resource Listing defaults to the GET method on /api-docs.{format}
  • The API Listing defaults to the GET method on /api-docs.{format}/{api-name} where {api-name} is the name of each API.

As trivial as this change sounds, it drastically improves the integration path. Now each API does not need to extend Swagger code, and the `/resources.{format}` path is no longer “reserved” (we were surprised to see how many people already had a /resources API!).

You can see the latest code in Github at https://github.com/wordnik/swagger-core. All samples are updated and the compiled binaries have been deployed to maven central. In addition, there is updated support for the following frameworks:

  • JAX-RS
  • Play2
  • RESTEasy
  • Grails

Updates to other frameworks will be following soon.

Finally, remember Swagger is free, open-source software, distributed under the Apache 2 license.

Feedback welcome! See our updated sample app.

The Wordnik Engineering Team

 

Share this:
Share this page via Email Share this page via Stumble Upon Share this page via Digg this Share this page via Facebook Share this page via Twitter

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>