Introducing Swagger

29,218 views

Published on

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

Published in: Technology, Education
4 Comments
19 Likes
Statistics
Notes
  • Hi, please join the google group for discussions about getting going with swagger:

    https://groups.google.com/forum/#!forum/swagger-swaggersocket
       Reply 
    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 http://petstore.swagger.wordnik.com/
    For this i have added swagger annotations in java class
    package com.mkyong;

    import javax.ws.rs.Consumes;
    import javax.ws.rs.GET;
    import javax.ws.rs.POST;
    import javax.ws.rs.Path;
    import javax.ws.rs.Produces;
    import javax.ws.rs.core.MediaType;
    //import javax.ws.rs.core.Response;

    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;

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

    @GET
    @Path('/get.json')
    @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') })

    @Produces(MediaType.APPLICATION_JSON)
    public Track getTrackInJSON() {

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

    return track;

    }

    /*@POST
    @Path('/post')
    @Consumes(MediaType.APPLICATION_JSON)
    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
    jersey-serlvetcom.sun.jersey.spi.container.servlet.ServletContainercom.sun.jersey.config.property.packagescom.mkyongcom.sun.jersey.config.property.packagescom.mkyong;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 ?
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • See here for generating static documentation:

    https://github.com/wordnik/swagger-codegen#generating-static-api-documentation
       Reply 
    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
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total views
29,218
On SlideShare
0
From Embeds
0
Number of Embeds
49
Actions
Shares
0
Downloads
298
Comments
4
Likes
19
Embeds 0
No embeds

No notes for slide

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 />http://petstore.swagger.wordnik.com/api/resources.json<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 />http://petstore.swagger.wordnik.com/api/pet.json<br />
  6. 6. API Response<br />Knowing input/output models is helpful!<br />Based on JSON Schema (Draft)<br />http://tools.ietf.org/html/draft-zyp-json-schema-03<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 />swagger.wordnik.com<br />See it in action<br />developer.wordnik.com/docs<br />Download the source/samples<br />swagger.wordnik.com/downloads<br />Discuss it<br />groups.google.com/group/wordnik-api<br />#swagger_doc on freenode<br />
  16. 16. Questions?<br />

×