# smartdoc-middleware

> Smartdoc is an RESTful document generator according to document-style comment

Latest version **0.0.11** (published 2017-04-13) · ISC license · 0 weekly downloads

## Install

```sh
npm install smartdoc-middleware
pnpm add smartdoc-middleware
yarn add smartdoc-middleware
bun add smartdoc-middleware
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.11 |
| Published | 2017-04-13 |
| First published | 2017-01-24 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | linkeo |
| Maintainers | linkeo |

## Links

- npm: https://www.npmjs.com/package/smartdoc-middleware
- Repository: https://github.com/linkeo/smartdoc-middleware
- Homepage: https://github.com/linkeo/smartdoc-middleware#readme
- Issues: https://github.com/linkeo/smartdoc-middleware/issues
- npm.io page: https://npm.io/package/smartdoc-middleware

## Dependencies (5)

- [ejs](https://npm.io/package/ejs.md) ^2.5.5
- [esprima](https://npm.io/package/esprima.md) ^3.1.3
- [express](https://npm.io/package/express.md) ^4.14.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^2.0.0
- [cli-color](https://npm.io/package/cli-color.md) ^1.1.0

## Recent versions

- 0.0.11 (latest) — 2017-04-13
- 0.0.10 — 2017-04-12
- 0.0.9 — 2017-04-12
- 0.0.8 — 2017-03-20
- 0.0.7 — 2017-03-07
- 0.0.6 — 2017-03-01
- 0.0.5 — 2017-02-24
- 0.0.4 — 2017-02-24
- 0.0.3 — 2017-02-23
- 0.0.2 — 2017-02-14
- 0.0.1 — 2017-01-24

## README

#smartdoc-middleware

Smartdoc is an RESTful document generator according to document-style comment.

## How it works

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.

## Usage

1. Install

    npm install --save smartdoc-middleware

### 2. Basic Usage

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:

```js
// 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`.

### 3. Writing API-Document Comments

First, you should declare an app like this (In any file inside the services folder, generally, services/index.js):

```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.

```js
// 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:

```yaml
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: ...
```



## Features

- 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.

## Todo

- [ ] More powerful request, with custom headers, cookies, etc.
- [ ] Support Environment, a scope to store some variables.
- [ ] Custom code, will run after response received.

---
_Source: https://npm.io/package/smartdoc-middleware · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._