rest-tool needs Node.js and NPM installed on the machine, before start installing and using it.
If you want to change the stylesheets of the generated documentation of the API, you will need Sass and Compass.
The rest-tool tool can be installed as any other node module, but you have to install to the global node_modules folder, so use the -g switch to npm.
To install rest-tool, execute the following command:
$ npm install -g rest-tool
To check, whether rest-tool is installed successfully, run the following command:
$ rest-tool -V
0.4.5
rest-tool utilityTo get help, use the -h option:
rest-tool -h
Usage: rest-tool [options] [command]
Commands:
create [options] <project-name> Create a new REST API project
docs [options] Documentation management
add [options] Add new service to the project
add-bulk [options] Add new services to the project in bulk mode
test [options] Test cases management
Options:
-h, --help output usage information
-V, --version output the version number
You can do the following things with rest-tool:
rest-tool create).rest-tool add, rest-tool add-bulk).rest-tool doc --update)rest-tool test --update)node server/server.js).You can get help to any of the commands using the following schema:
$ rest-tool <command> -h
for example:
$ rest-tool docs -h
Usage: docs [options]
Options:
-h, --help output usage information
-u, --update Generate the HTML format documentation
-c, --config <configFileName> The name of the configuration file (default: config.yml)
-v, --verbose Verbose mode
The following sections describe the usage of the commands in details.
Create the project:
$ rest-tool create <project-name>
for example:
$ rest-tool create crm-api
After, you have created the new project, move into the new projects folder, and install those node modules, the new project needs:
$ cd crm-api
$ npm install
Start the mock server from the console:
$ node server/server.js
The server starts and should write something like this:
{ documentRoot: '../webui',
port: 3007,
restapiRoot: '..',
useRemoteServices: false,
environment: 'development' }
restapi config: { projectName: 'crm-api',
apiVersion: 'v0.0.0',
author: 'TBD.',
licence: 'TBD.',
serviceUrlPrefix: '/rest',
servicePort: 3007,
baseUrl: 'http://localhost:3007/rest',
servicesRoot: 'services',
services: [ '/monitoring/isAlive' ],
loginCredentials: { user: 'username', pass: 'password' } }
register service GET /monitoring/isAlive
/monitoring/isAlive
Express server listening on port 3007 in development mode
As you can see, the server is running, and listening on 3007 port.
It uses a base URL that is: http://localhost:3007/rest and
the /monitoring/isAlive service is already registered.
It is a predefined service which can be used as an example for defining new services
as well as it provides a service that immediately should work, and makes easier the troubleshooting if something is wrong with the creation of the project.
You can see its descriptor under the services folder:
services/
└── monitoring
└── isAlive
└── service.yml
Try to call this service with a browser or a command line utility, and you should get
a true value as a response:
$ curl http://localhost:3007/rest/monitoring/isAlive
true
Open a new terminal, then go into the newly created 'crm-api' project folder, and generate the test cases using the 'rest-tool':
$ rest-tool test --update
Update test cases or create them, if they are missing.
Existing files will not be overwritten
A new test case should be generated under the 'test' folder, based on the 'templates/test/testDelMethod.mustache' template.
Check whether a test case is really there:
$ tree test/
test/
└── Get Monitoring Is Alive.js
0 directories, 1 file
Run the test case to make sure, it is working:
$ mocha
.
✔ 1 tests complete (24ms)
You can also do it via make:
$ make test
Successfully checks if server is alive
✓ should Successfully checks if server is alive
1 passing (22ms)
Generate the documentation for the predefined service with the following command:
$ rest-tool docs --update
The following files will be generated:
$ tree docs
docs
├── images
│ └── grid.png
├── index.html
├── js
│ ├── jquery-1.9.0
│ │ ├── jquery-1.9.0.js
│ │ └── jquery-1.9.0.min.js
│ └── restapidoc.js
├── README.md
├── sass
│ ├── ie.scss
│ ├── partials
│ │ └── _base.scss
│ ├── print.scss
│ └── screen.scss
├── services
│ └── monitoring
│ └── isAlive
│ ├── service.html
│ └── service.yml
└── stylesheets
├── ie.css
├── print.css
└── screen.css
9 directories, 15 files
Now you can view the generated documentation with a browser either as a static content
opening the docs/index.html or through the server using the http://localhost:3007/docs/ URL.
Create a collection manager service with the following command:
$ rest-tool add -t COLLECTION \
-p customers \
-u /customers \
-n Customers \
-d "A service to manage the collection of customers"
And check what is created under the services folder:
$ tree services/
services/
├── customers
│ ├── getCollection-responseBody.json
│ ├── postCollection-requestBody.json
│ ├── postCollection-responseBody.json
│ └── service.yml
└── monitoring
└── isAlive
└── service.yml
3 directories, 5 files
Add the newly created server to the services list in the config.yml file:
projectName: crm-api
apiVersion: v0.0.0
author: TBD.
licence: TBD.
serviceUrlPrefix: /rest
servicePort: 3007
baseUrl: http://localhost:3007/rest
servicesRoot: services
services:
- /monitoring/isAlive
- /customers # Add this entry!!!
# To add new services,put here the path of
# the directory that contains the service.yml
loginCredentials:
user: username
pass: password
Then you should restart the server, and the service is working with the predefined settings and mock data:
$ curl http://localhost:3007/rest/customers
[
{
"id": 1,
"data": "some mock data"
},
{
"id": 2,
"data": "some mock data"
}
]
In order to learn more about creating and configuring services, read the documentation pages.