Sat, 15 December 2012
- Joined by Tony Tam, lead developer of Swagger, and Wordnik CEO.
- Swagger is a framework for describing and producing REST APIs.
- The specification component describes the endpoints, the parameter types and counts, input validations, and the resulting data models.
- Once you have the specification:
- swagger-ui can produce a beautiful documentation page for you.
- swagger-codegen can produce a client for you, in many languages
- Unlike WSDL and WADL/2, Swagger is simple, Json-based, and not meant to solve every problem. Some APIs cannot use Swagger.
- Relatively complex model objects can be described, even polymorphic types.
- Even though the specification is in Json, the APIs can choose to accept XML or other formats as input.
- Swagger also produces a service description that can be examined at run-time. This allows more granular access and documentation for different users of the API.
- Some web frameworks integrate Swagger support, allowing you to put the service description in the code, instead of in a separate Json file. Integrations exist for JAX-RS, Play 1, Play 2, Node.js, Sinatra, Symfony, Restler, Django, and Scalatra (which has the "cleanest" integration).
- swagger-codegen uses Mustache templates to produce clients in Scala, Java, Ruby, PHP, Python, Python 3, ActionScript, JavaScript, and Objective-C.
- Generation in the other direction is possible too. Given a Swagger specification, the code generator can write a Node.js, Ruby, or Scalatra API server.
- Chicken or egg? Write the Json API spec and generate a server, or write the server with Swagger support and generate the Json API spec?
- Swagger encourages best practices by focusing on the interface of your API.
- Swagger does not attempt to solve the REST versioning problem. It can facilitate, however, with version paths. Alternatively, a client can examine the run-time description representation and change its behavior according to changes in the API.
- Upcoming: supporting descriptions of authentication, including OAuth.
- Upcoming: supporting descriptions of protocol (e.g., http vs. https).
- Upcoming: supporting descriptions of format, without the need for path prefixes/suffixes (e.g., Json vs. XML).
- swagger-socket allows you to document a wire protocol with full-duplex communication with minimal latency and chatter. Native integration with Scalatra (via Atmosphere) is underway.
- Atmosphere takes the extreme pain out of WebSocket development, transparently solving issues related firewalls, proxies, browser vendors/versions, protocol formats, and HTTP/1.1 fallback.
- Like actor-based systems, sockets are hard to document!
- Community contributions are welcome on GitHub, especially on the code generator (new languages, frameworks, and better implementations).
- #swagger on freenode
Direct download: 25-tony-tam.mp3
Category: interview
-- posted at: 6:48 PM
|
Follow us on twitter!
