restful-api-tool
quickly create restful style mock server.
Last updated a month ago by lemonclown .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install restful-api-tool 
SYNC missed versions from official npm registry.

npm version npm download npm license git action

Introduction

  • In brief, the purpose of this project is to achieve: ts type -> JSON-Schema -> mock data -> restful mock-server

    • ts type -> JSON-Schema: That is, the types defined using typescript are converted to JSON-Schema, see typescript-json-schema

    • JSON-SCHEMA -> mock-data: That is to generate mock data through json-schema, see json-schema-faker

    • mock-data -> mock-server: That is, define the relationship between the model (JSON-Schema or ts type) and the API is in some configuration files, and through these configurations to generate a restful-style mock server

  • This tool provides three sub-commands: init, generate and serve

    • The init sub-command generates a template project, changes the configuration and adding or deleting models as needed to quickly generate a mock server

    • The generate sub-command parses the configuration file and generates a JSON-Schema for the specified model. You can copy the JSON-Schema into a platform similar to yapi which support importing JSON-Schema to quickly define the request or response models in the API page.

    • The serve sub-command parses the configuration file to generate a mock server

      • You can specify the directory of the mock data file, so that the files under this file directory are preferentially proxyed as the response data;
      • In addition, serve also supports custom routing, which is based on koa and koa-router. If you want to support custom routing while generating mock server, see below

  • 简单地来说,这个工程的目的是实现:ts 类型 --> JSON-Schema --> mock data --> restful mock-server

    • ts 类型 --> JSON-Schema: 即把 ts 定义的类型转为 JSON-Schema,可见 typescript-json-schema

    • JSON-SCHEMA --> mock-data: 即通过 json-schema 生成 mock 数据,可见 json-schema-faker

    • mock-data --> mock-server: 即通过配置文件定义模型(JSON-Schema 或 ts 类型)和 api 的关系,以生成 restful 风格的 mock 服务器

  • 该工具提供了三个子命令:initgenerateserve

    • init 子命令生成一个模板工程,按需更改配置和增添模型,以快速生成 mock server

    • generate 子命令解析配置文件,将指定的模型生成 JSON-Schema,你可以将该 JSON-Schema 拷贝进类似 yapi 的支持导入 JSON-Schema 的平台中,即可快速定义接口文档中的请求/响应对象

    • serve 子命令解析配置文件,生成一个 mock server

      • 你可以指定 mock data 文件的目录,使得优先代理此文件目录下的文件作为响应数据;
      • 此外,serve 还支持自定义路由,它基于 koakoa-router,如果你想要在生成 mock server 的同时还支持自定义路由的话,可参见下文

Install

# Global installation
yarn global add restful-api-tool
# or use npm: npm install -g restful-api-tool

# Init mock server project
rapit init demo-mock-server --log-level verbose

# or use npx: npx restful-api-tool init demo-mock-server -- --log-level verbose

Cli Usage

cd demo-mock-server
yarn serve:cli

Usage

$ rapit --help

Usage: command [options] [command]

Options:
  -V, --version                              output the version number
  -c, --config-path <config-path>            specify the file path of main config (absolute or relative to the cwd) (default: "app.yml")
  -f, --api-config-path <api-config-path>    specify the file/directory path of api-item config file (absolute or relative to the cwd) (default: "api.yml")
  -s, --schema-root-path <schema-root-path>  specify the root path of schema (absolute or relative to the cwd) (default: "schemas")
  --encoding <encoding>                      specify encoding of all files. (default: "utf-8")
  --log-level <level>                        specify logger's level.
  -h, --help                                 output usage information

Commands:
  generate|g [options] <project-dir>
  serve|s [options] <project-dir>
  init|i <project-dir>

init

$ rapit init --help
Usage: rapit init|i [options] <project-dir>

Options:
  -h, --help  output usage information

generate

$ rapit generate --help

Usage: command generate|g [options] <project-dir>

Options:
  -p, --tsconfig-path <tsconfigPath>  specify the location (absolute or relative to the projectDir) of typescript config file.
  -I, --ignore-missing-models         ignore missing model.
  --clean                             clean schema folders before generate.
  -h, --help                          output usage information

serve

$ rapit serve --help

Usage: command serve|s [options] <project-dir>

Options:
  -h, --host <host>                                    specify the ip/domain address to which the mock-server listens.
  -p, --port <port>                                    specify the port on which the mock-server listens.
  --prefix-url <prefixUrl>                             specify the prefix url of routes.
  --mock-required-only                                 json-schema-faker's option `requiredOnly`
  --mock-optionals-always                              json-schema-faker's option `alwaysFakeOptionals`
  --mock-optionals-probability <optionalsProbability>  json-schema-faker's option `optionalsProbability`
  --mock-use-data-file-first <mockDataFileRootPath>    specify the mock data file root path.
  --mock-data-file-first                               preferred use data file as mock data source.
  -h, --help                                           output usage information

Programming Usage

yarn add --dev restful-api-tool
# or use npm: npm install --save-dev restful-api-tool

Usage

  • Omit files defined in Demo...

  • create a script file named script/server.ts, and add content like this:

    import path from 'path'
    import chalk from 'chalk'
    import { execCommand, Router, ServeCommand, SubCommandHook } from 'restful-api-tool'
    
    async function serve () {
      const projectDir = path.resolve()
      const args = ['', '', 'serve', projectDir, '--log-level=debug', '-s', 'schemas/answer']
      console.log(chalk.gray('--> ' + args.join(' ')))
    
      const serve = new ServeCommand()
      serve.onHook(SubCommandHook.BEFORE_START, (server, context) => {
        const router = new Router({ prefix: context.prefixUrl })
        router.get('/hello/world', ctx => {
          ctx.body = {
            code: 200,
            message: 'Got it!',
          }
        })
        server.registerRouter(router)
      })
    
      execCommand(args, { serve })
    }
    serve()
    
  • Here we customize a route GET /{context.prefixUrl}/hello/world, combined with the definition in Demo, where the value of context.prefixUrl is /mock, so the route path is /mock/hello/world

  • run the command node -r ts-node/register script/serve.ts to start the mock server, and the custom route GET /mock/hello/world also will be registered in the server

Demo

  • Create an empty ts project

  • Add a tsconfig.json file (you can specify other paths through -p, --tsconfig-path <tsconfig-path> in the sub-command generate), as follows

    {
      "compilerOptions": {
        "strict": true,
        "moduleResolution": "node",
        "strictNullChecks": true,
        "noUnusedLocals": false,
        "noUnusedParameters": false,
        "noImplicitAny": true,
        "noImplicitThis": true,
        "noImplicitReturns": false,
        "alwaysStrict": true,
        "suppressImplicitAnyIndexErrors": true,
        "newLine": "LF",
        "noEmitOnError": true,
        "pretty": false,
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true
      },
      "include": [
        "src"
      ]
    }
    
  • Add a package.json file, like this:

    {
      "name": "restful-api-tool---demo",
      "version": "0.0.0",
      "private": true,
      "scripts": {
        "build:schemas": "rapit generate .",
        "serve:cli": "nodemon --exec \"yarn build:schemas && rapit serve .\"",
        "serve:program": "nodemon --exec \"yarn build:schemas && node -r ts-node/register script/serve.ts\""
      },
      "devDependencies": {
        "nodemon": "^1.19.1",
        "restful-api-tool": "^0.0.5",
        "ts-node": "^8.4.1",
        "typescript": "^3.6.3"
      }
    }
    
  • Add a project configuration file named app.yml (other paths can be used, but the command-line option -c, --config-path <config-path> needs to be used to specify the path of the custom project configuration file), the content is as follows:

    globalOptions:
      encoding: utf-8
      logLevel: debug
    
    generate:
      clean: true
      ignoreMissingModels: true
      ignoredDataTypes:
        - 'undefined'
      schemaArgs:
        ref: false
        required: true
    
    serve:
      host: '0.0.0.0'
      port: 8091
      prefixUrl: /mock
      mockDataFileFirst: true
      mockDataFileRootPath: data/
      mockOptionalsAlways: true
      mockOptionalsProbability: 0.7
    
  • Add a configuration file api.yml that defines the API routes (you can specify other paths through the -f, --api-config-path <api-config-path>option), the content is like:

    api:
      user:
        path: /api/user
        response:
          headers:
            Content-Type: application/json; UTF-8
        items:
          login:
            path: /login
            method: POST
            title: 登录
            response:
              fullModelName: CurrentUserInfoResponseVo
          logout:
            path: /logout
            method: POST
            title: 退出登录
    
    • Here we define two routes:

      • POST /api/user/login, with request object model named UserLoginRequestVo (specified by response.fullModelName in the configuration) and response object model named CurrentUserInfoResponseVo

      • POST /api/user/logout, with request object model named UserLogoutRequestVo and response object model named UserLogoutResponseVo

    • For more configuration details, see the class RawApiConfig defined in src/core/types/api-config.ts

  • Write the interface of the data model named UserLoginRequestVo, CurrentUserInfoResponseVo, UserLogoutRequestVo and UserLogoutResponseVo

  • Generate the schemas or start a mock server in the way mentioned above: Cli Usage and Programming Usage

More

Current Tags

  • 0.0.7                                ...           latest (a month ago)

7 Versions

  • 0.0.7                                ...           a month ago
  • 0.0.6                                ...           a month ago
  • 0.0.5                                ...           2 months ago
  • 0.0.4                                ...           2 months ago
  • 0.0.3                                ...           2 months ago
  • 0.0.2                                ...           2 months ago
  • 0.0.1                                ...           2 months ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 7
Last Day 7
Last Week 7
Last Month 27
Dependencies (25)
Dev Dependencies (17)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |