Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Introducing Swagger


Published on

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

Published in: Technology, Education
  • Hi, please join the google group for discussions about getting going with swagger:!forum/swagger-swaggersocket
    Are you sure you want to  Yes  No
    Your message goes here
  • Hi tam
    I am new to programming i want to generate interactive documentation as
    For this i have added swagger annotations in java class
    package com.mkyong;


    import com.mkyong.Track;
    import com.wordnik.swagger.core.Api;
    import com.wordnik.swagger.core.ApiErrors;
    import com.wordnik.swagger.core.ApiError;
    import com.wordnik.swagger.core.ApiOperation;

    @Api(value = '/json/metallica', description = 'Operations about singer')
    public class JSONService {

    @ApiOperation(value = 'Find singer', notes = 'Add extra notes here', responseClass = 'com.mkyong.JSONService')
    @ApiErrors(value = { @ApiError(code = 400, reason = 'singer not found'),
    @ApiError(code = 404, reason = 'singer not found') })

    public Track getTrackInJSON() {

    Track track = new Track();
    track.setTitle('Enter Sandman');

    return track;


    public Response createTrackInJSON(Track track) {

    String result = 'Track saved : ' + track;
    return Response.status(201).entity(result).build();

    And in swagger ui ,in index.html i have given discovery url-http://localhost:8080/RESTfulExample/json/metallica/get.json
    my web.xml is;com.wordnik.swagger.jaxrs.listingcom.sun.jersey.api.json.POJOMappingFeaturetrue1jersey-serlvet/rest/*

    I am getting an error cant read swagger json
    it is unable to load swagger ui
    do i need to add anything else ?
    Are you sure you want to  Yes  No
    Your message goes here
  • See here for generating static documentation:
    Are you sure you want to  Yes  No
    Your message goes here
  • How do i generate documentation of my rest webservices with using swagger annotation only for example @documentation ,could there be such annotation where i provide output path and documentation get automatically generated .Thanks in advance
    Are you sure you want to  Yes  No
    Your message goes here

Introducing Swagger

  1. 1. Introduction to Swagger<br />Tony Tam<br />@fehguy<br />
  2. 2. Why Swagger?<br />Integration with REST APIs is troublesome and inconsistent<br />Different vendors have different REST semantics<br />Client libraries vary wildly by vendor, language<br />Documentation for developers is an afterthought<br />Input parameters, allowable values, models, responses are found via trial & error<br />Internally a PITA<br />YOUR API is too hard to develop against!<br />
  3. 3. How Does it Work?<br />Your server produces a Resource List<br />All available APIs<br /><br />“It’s like a sitemap for your API!”<br />
  4. 4. How Does it Work?<br />Each API declares itself<br />Available operations<br />Parameters<br />Type (path, query, body)<br />Allowable values/data types<br />Input/output models<br />Error responses with descriptions<br />
  5. 5. API Response<br /><br />
  6. 6. API Response<br />Knowing input/output models is helpful!<br />Based on JSON Schema (Draft)<br /><br />
  7. 7. But what’s the benefit?<br />A Sandbox!<br />
  8. 8. Client Library Generation<br />Code generation based on Resource Spec<br />Template-based Framework<br />Consume REST Methods, Models, Parameters<br />Produce client libraries<br />“Know before you go HTTP”<br />Required values, fields are known by the client<br />Only expose what’s allowed!<br />Swagger filtering removes methods/models you don’t have access to<br />
  9. 9. Client Library Generation<br />Super user access<br />Ordinary dev access<br />
  10. 10. Test Framework<br />JSON-driven tests for your Client + API<br />Expected data<br />Test Suites<br />
  11. 11. Test Framework<br />
  12. 12. Easy to add<br />For Java/Scala via JAX-RS…<br />Add swagger-core.jar<br />Annotate your models per your @Providerclass<br />Annotate your resources<br />
  13. 13. Easy to add<br />For node.js via express<br />Require swagger.js<br />Declare your swagger specs, models<br />Could use AST/DSL to do automatically<br />Add your operations, configure and start<br />
  14. 14. Easy DIY<br />The Swagger spec is Language Agnostic!<br />ANY swagger-compliant server can…<br />Use the Swagger client lib generator<br />Use the test framework<br />Use the sandbox UI<br />More server support from Wordnik<br />Play, Rails<br />.net, others community developed<br />
  15. 15. Where to go Next<br />Try Swagger<br /><br />See it in action<br /><br />Download the source/samples<br /><br />Discuss it<br /><br />#swagger_doc on freenode<br />
  16. 16. Questions?<br />