Description

Coming soon...

Usage

Dependencies

• Ruby (1.8x or 1.9x)
• Gem
• JSON gem (gem install json)

Parameters

 $ bin/source2swagger

 Usage: source2swagger [options]
 -i, --input PATH                 Directory of the input source code
 -e, --ext ("rb"|"c"|"js"|"py")   File extension of the source code
 -f, --file FILENAME              Overwrites options: -i and -e. Takes a single annotated source code file
 -c, --comment ("##~"|"//~")      Comment tag used to write docs
 -o, --output PATH                Directory where the json output will be saved (optional)

Example

  $ bin/source2swagger -i ~/project/lib -e "rb" -c "##~"

This will output the Swagger compatible JSON specs on the terminal.

For this example the file annotated with the swagger spec are ruby files (-e "rb"). The annotations started with ##~ to distinguish them from normal ruby comments that start #.

The source code is on the directory ~/project/lib , note that the path is handled recursively, it will analyze all ruby file under the declared path.

You can also target a single file setting the option -f

  $ bin/source2swagger -f ~/data/test/sample3.rb -c "##~"

Add -o /tmp and it will write the JSON file(s) to /tmp

Contributions

Feel free to extend the code and issue a pull request,

The test suite can be invoked as

  $ rake test

Requires rake and the gem test/unit

How to

Check test/data/sample3.rb for a comprehensive real example of the source2swagger inline docs for Ruby.

The names of the attributes can be seen on the section Grammar (partially) or better yet in the original Swagger Specification.

API names declaration

First you need to declare the API

  ##~ a = source2swagger.namespace("your_api_spec_name")

This will generate the file your_api_spec_name.json. The name can be declared in multiple files and several times in the same file. Each time namespace is invoked it returns the reference to the root element of the API named "your_api_spec_name".

Setting attributes elements

One by one,

  ##~ a.basePath = "http://helloworld.3scale.net"
  ##~ a.swaggerVersion = "0.1a"
  ##~ a.apiVersion = "1.0"

or all at the same time,

  ##~ a.set "basePath" => "http://helloworld.3scale.net", "swaggerVersion" => "0.1a", "apiVersion" => "1.0"

You can always combine

  ##~ a.set "basePath" => "http://helloworld.3scale.net", "swaggerVersion" => "0.1a"
  ##~ a.apiVersion = "1.0"

Adding and element to a list attribute

  ##~ op = a.operations.add   
  ##~ op.httpMethod = "GET"
  ##~ op.tags = ["production"] 
  ##~ op.nickname = "get_word"
  ##~ op.deprecated = false
  ##~
  ##~ op = a.operations.add
  ##~ op.set :httpMethod => "POST", :tags => ["production"], :nickname => "set_word", :deprecated => false

Two elements (operations) were added to a.operations, you can also add directly if you do not need to have a reference to the variable op

  ##~ a.operations.add :httpMethod => "GET", :tags => ["production"], :nickname => "get_word", :deprecated => false
  ##~ a.operations.add :httpMethod => "POST", :tags => ["production"], :nickname => "set_word", :deprecated => false

Using variables for common structures

The source2swagger notation also allows you to define variables that can be defined anywhere on the source code files as @name = value, the value is typically a hash structure in ruby notation ({"key_1" => "value_1", ... , "key_n" => "value_n"})

Note: all variable declarations are evaluated before the non-variable statements so vars will always available no matter where they are defined. For instance,

... 
##  in foo.rb
##~ op.parameters.add @parameter_app_id
...
## in bar.rb
##~ @parameter_app_id = {"name" => "word", "description" => "The word whose sentiment is to be set", "dataType" => "string", "required" => true, "paramType" => "path"}
...

Adding comments

You can add comments on the inline docs specification, just use the normal comment tags of your language

##~ op = a.operations.add   
##
##  HERE IS MY COMMENT (do not use the comment tag, e.g. ##~ but the comment tag specific of your language, in ruby #)
##
##~ op.httpMethod = "GET"

Check test/data/sample3.rb for a comprehensive real example of the source2swagger inline docs for Ruby.

Grammar

(partial)

For a more comprehensive specification of the fields needed to declare your API on the Swagger format you can always go to the source

  $ROOT

  a = source2swagger.namespace(STRING)

  a.basepath = STRING             [required, ]
  a.swaggerVersion = STRING       []
  a.apiVersion = STRING           []
  a.apis = LIST[$ENDPOINTS]       [required, ]

  a.models = LIST[$MODELS]        []

  $ENDPOINTS

  e = a.apis.add

  e.path = STRING                 [required, ]
  e.format = LIST[STRING]         [required, ]
  e.description = STRING          [required, ]
  e.errorResponses = LIST[$ERRORS][]
  e.operations = LIST[$OPERATIONS][]

  $OPERATIONS

  o = e.operations.add

  o.httpMethod = STRING           [required, ]
  o.tags = LIST[STRING]           []
  o.nickname = STRING             []
  o.deprecated = BOOLEAN          []
  o.summary = STRING              []
  o.responseClass = STRING        []
  o.parameters = LIST[$PARAMETERS][]

  PARAMETERS

  p = o.parameters.add

  p.name = STRING                 [required]
  p.description = STRING          []
  p.dataType = STRING             [required]
  p.allowMultiple = BOOLEAN       []
  p.required = BOOLEAN            []
  p.paramType = STRING

  ERRORS

  err = e.operations.add

  err.reason = STRING             []
  err.code = INT                  []

Extra Resources

You can edit and view the generated Swagger JSON specs online here: JSON Editor

It's pretty basic but it works great for a quick manual inspection and edition of the json generated by source2swagger. If you know of another online editor please let us know.

License

MIT License