malachheb / calamum Goto Github PK

View Code? Open in Web Editor NEW

78.0 7.0 50.0 584 KB

Rest Api documentation generator

Ruby 30.44% HTML 27.18% CSS 42.38%

calamum's Introduction

calamum

Calamum is a simple tool to generate a REST API documentation from a JSON file definition.

Installation

Download and install calamum: gem install calamum

Usage

calamum -h
Usage: /bin/calamum (options)
  -d, --debug                      Show actions to do (true by default)
  -f, --file DEFINITION            Path to the file with API definition
  -p, --path PATH                  Path to the directory where docs will be generated
  -t, --template TEMPLATE          Name of HTML template (twitter or bootstrap , twitter by default)
  -s, --sort                       Sort the resources alphabetically
  -v, --version                    Show version number
  -h, --help                       Show this help

To generate a documentation you should write a definition of your REST API in JSON format or YAML format.
In the case of separated resources files, the resources attribute must define the directory path of resources files as in the files sample_separated.json and sample_separated.yml.
You could find an example of API definition in the sample.json and sample.yml. Next, just run the calamum command.

for twitter template:

$calamum -f my_api_definition.json -t twitter

for bootstrap template:

$calamum -f my_api_definition.json -t bootstrap

To preview just generated documentation, navigate to the 'docs' directory (by default in your home path, you can specify the destination path with the option '-p/--path'). Then, find and open the index.html file in your browser and enjoy the result.

Inspirations

calamum's People

Contributors

Stargazers

Watchers

calamum's Issues

Header in HTML tab

I have tried to add header by different ways but could not succeed, can you please tell me how can i added header to API documentation.

Accept: application/vnd.example.v1
Content-Type: application/json

"header": {
"Accept": {
"type": "string",
"description": "application/vnd.example.v1",
"required": true
},
"Content-Type": {
"type": "string",
"description": "application/json",
"required": true
}
},

enable -s won't sort resources based on the key values

In doc_parser.rb, we put each resource into a Hash.
Ln 5 "@resources = Hash.new"
then in the twitter template, we read it by
Ln 32 "<% @resources.each do |name, endpoints| %>"
which can't ensure read resources in sequence.

what about reading it by:

<% @resources.sort.map do |name, endpoints| %> ?

$> calamum
/home/vagrant/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:55:in `require': cannot load such file -- pry (LoadError)
        from /home/vagrant/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:55:in `require'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/gems/calamum-1.1.0/lib/calamum.rb:5:in `<top (required)>'
        from /home/vagrant/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:55:in `require'
        from /home/vagrant/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:55:in `require'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/gems/calamum-1.1.0/lib/calamum/runner.rb:1:in `<top (required)>'
        from /home/vagrant/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:55:in `require'
        from /home/vagrant/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:55:in `require'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/gems/calamum-1.1.0/bin/calamum:8:in `<top (required)>'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/bin/calamum:23:in `load'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/bin/calamum:23:in `<main>'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/bin/ruby_executable_hooks:15:in `eval'
        from /home/vagrant/.rvm/gems/ruby-1.9.3-p484/bin/ruby_executable_hooks:15:in `<main>'

After running gem install pry calamum works as expected.