Document client SDK

[jpangburn]

I'm trying to generate a Javascript SDK for my API and find that there's no good way to generate documentation for how a user would use that SDK to connect to my API. The swagger doc shows HTTP methods and URLs but those don't matter to the client SDK user- what matters to them is what methods they call in the SDK, and what parameters those methods take.
It seems like swagger-codegen has all the data available needed to generate such a static HTML documentation for a generated SDK. This should also generate doc for a Javascript SDK too please.

[wing328]

@jpangburn for JS SDK, do you actually mean http://github.com/swagger-api/swagger-js?

Currently, swagger-codegen does not offer a JS (client-side) code generator.

[jpangburn]

Hi,
I think swagger-js can’t work because they generate a dynamic client. Swagger-codegen has the right architecture to be generating a client SDK in different languages, and from the same data structure that you generate that code you can also generate the documentation for it. At least that’s how it appears to me. If you disagree, of course reject this.

thanks,
Jesse

On Sep 24, 2015, at 5:53 PM, wing328 notifications@github.com wrote:

@jpangburn https://github.com/jpangburn for JS SDK, do you actually mean http://github.com/swagger-api/swagger-js https://github.com/swagger-api/swagger-js?

Currently, swagger-codegen does not offer a JS (client-side) code generator.

—
Reply to this email directly or view it on GitHub #1294 (comment).

[wing328]

We'll mark this as a feature request (there's a similar request before) and we're looking for contribution from the community to implement the JS SDK in swagger codegen.

[jfiala]

Added PR #1671, here are the details of the currently added changes to support Javascript SDKs:

Add basic Javascript SDK support

(based on the Java templates):

• Allow to generate model classes
  • including comments
  • including property-level comments + type hints
  • including getters & setters + comment type hints
  • generate inline Enumeration classes to allow Enumeration usage
  • add required parameters to default constructor
  • add .toJson() to print complete model including nested models
• Allow to generate API classes
  • including comments
  • including JSDoc for params & return
• Allow for both AMD + plain JS usage

Sample model output:

function StateEnum() {
    var self = this;

    self.ACTIVE = "ACTIVE",
    self.DISABLED = "DISABLED";

}

/**
 * User object
 **/
function User(id, lastname, firstname) { 
    var self = this;

    /**
      * First name of the user
      * datatype: String
      * required
      **/
      self.firstname = firstname;

...  

    self.constructFromObject = function(data) {

        self.firstname = data.firstname;

        self.id = data.id;

        self.lastname = data.lastname;

        self.location.constructFromObject(data.location);

        self.nickname = data.nickname;

        self.state = data.state;

    }


  /**
   * get First name of the user
   * @return {String}
   **/
  self.getFirstname = function() {
    return self.firstname;
  }

  /**
   * set First name of the user
   * @param {String} firstname
   **/
  self.setFirstname = function (firstname) {
    self.firstname = firstname;
  }
  ...


  self.toJson = function () {
    return JSON.stringify(self);
  }
}

Sample invocation with SDK support

Sample invocation in Javascript after generating the SDK (first save the user object, then read it again):

var myGlobalUser = new User();

/**
 * basic example to create and read a User
 */
function callApiSwagger() {

    var myUser = new User(1, 'surname', 'my first name');
    myUser.setState(StateEnum.ACTIVE);
    myUser.getLocation().setCity("Vienna");
    console.log('request: ' + myUser.toJson());

    var myUsercrudApi = new UsercrudApi();

    myUsercrudApi.saveUserCompleteUsingPOST1(myUser, 
        /**
         * @param {User} response
         */
        function (response, textStatus, jqXHR) {
            console.log('firstname: ' + response.getFirstname());
            console.log('location.city: ' + response.getLocation().getCity());
            console.log('response: ' + response.toJson());

            myUsercrudApi.getUserUsingGET1(response.getId(), 
                /**
                 * @param {User} response
                 */
                function (response, textStatus, jqXHR) {
                    console.log('location.city: ' + response.getLocation().getCity());

                    myGlobalUser.setFirstname(response.getFirstname() + " in " + response.getLocation().getCity());
            });
        });


}

Sample invocation before without SDK support

And this is what the invoking code looked before with plain ajax:

/**
 * basic example to create and read a User
 */
function callApi() {

    var backend_url = 'http://localhost:8080/user';
    var data = {id: 1, firstname: 'my first name', lastname: 'surname', state: 'ACTIVE', location: { city: 'Vienna' }};
    var json_data = JSON.stringify(data);
    console.log('request: ' + json_data);

    var options = {type: "post", async: true, contentType: "application/json", dataType: "json", data: json_data};
    var request = $.ajax(backend_url, options, data);

    request.done(function(response){

        console.log('firstname: ' + response.firstname);
        console.log('location.city: ' + response.location.city);
        console.log('response: ' + JSON.stringify(response));       

        var queryString = '?id=' + response.id;
        var url = backend_url + queryString;

        var options = {type: "get", async: true, contentType: "application/json", dataType: "json"};
        var request = $.ajax(url, options, data);
        request.done(function(response){

            console.log('location.city: ' + response.location.city);

            myGlobalUser1.firstname = response.firstname + " in " + response.location.city;
        });


    });


}