#smartdoc-middleware
Smartdoc is an RESTful document generator according to document-style comment.
Smartdoc reads all API-Document comments in service folder by AST, generates a delaration data file, then serve a single-page application for browsering and testing interfaces at the mounted route.
-
Install
npm install --save smartdoc-middleware
For example, we have an project like this:
- index.js
+ services // The directory where api functions defined in.
- user.js
- post.js
- ...
And you've commented these service functions correctly. (See below)
Then, you can easily extend your app with smartdoc:
// index.js
const app = require('express')();
const smartdoc = require('smartdoc-middleware');
const pathToServices = path.join('../services');
// ...
app.use('/doc', smartdoc(pathToServices));
// ...
app.listen(3000);
Then, you will able to access the document page at http://localhost:3000/doc
.
First, you should declare an app like this (In any file inside the services folder, generally, services/index.js):
// services/index.js
/**
* Example Application
* @application example-app
*
* @author linkeo
* @version 0.0.1
*/
module.exports = {};
Notice: To declare an Application,
@application [name]
is necessary.
Then, in every service modules, declare your APIs.
// services/user.js
/**
* User Services
* @module user
* @path /user
*/
module.exports = class UserService {
/**
* User Login
*
* @note If success, will set cookies with response.
*
* @route {post} /login
* @param {String} account Phone or email of the user
* @param {String} password
* @param {String} from Where the user logins, can be 'app', 'web'
* @return {Object} An object contains user information
*/
*login(req, res) {
//...
}
}
Notice: To declare a Module,
@module [name]
is necessary.Notice: To declare an Action,
@route [method] [path]
is necessary.
Then, you will get an API declaration structure like this:
name: example-app
title: Example Application
modules:
- name: user-674e7e
title: User Services
path: /user
actions:
- name: post-login-768ed4
title: User Login
route:
method: post
path: /login
params: ...
- Read document-style comment of RESTful interface.
- Serve a single-page application to display informations about your interfaces, e.g. method, path, params.
- Can send request to test your interface.
- More powerful request, with custom headers, cookies, etc.
- Support Environment, a scope to store some variables.
- Custom code, will run after response received.