Design, documentation and mock data fo API development
- nodeJS
- (optional) Atom IDE - for API Blueprint editing and preview
- (optional) Some Atom API Blueprint Packages:
- (optional) A REST client which can import API Blueprint files. Paw is a great client but not free. Postman (free) also has a Blueprint tool. You can also create a free account on https://apiary.io/ and edit Blueprint files and test them there.
NOTE: The IntelliJ IDEA Blueprint Plugin does not work.
-
Install nodeJS
-
(optional) Install Blueprint editor and preview IDE
-
(optional) Install Atom API Blueprint Packages
-
(optional) Install REST client
-
Install grunt-cli and aglio globally:
$ npm install grunt-cli aglio -g -
Fork and clone repo
-
Navigate into app directory and install node modules:
$ npm install
-
Documentation follows the API Blueprint Format.
-
To allow the separation of requests, responses, and schemas as separate json files as well as resources as separate blue print files, hercule is used.
-
The structure of the spec should be as follows, i.e. for the alarm API:
├── alarm │ ├── alarm.apib │ └── includes │ ├── alarm-errors.json │ ├── alarm-request.json │ ├── alarm-response.json │ ├── alarm-schema.json │ ├── alarm.md │ └── alarms.md
-
Run grunt command to build compiled API Blueprint file and HTML documentation making sure to include the API name you included in the api directory, i.e. if the API directory and .apib was named
alarmthe command to run would be:$ grunt build:alarm
$ node index.js
The mock and documentation server used is drakov.
The server will be running on http://localhost:4007.
API Documentation will be on http://localhost:4007.
The API routes as defined in the documentation will be shown in the console after the server has been started, i.e.
