Skip to content

user_manual

ThreeTree edited this page Feb 4, 2017 · 12 revisions

Table of Contents generated with DocToc

Create your account

Login and register

Press Register button on the right top corner, fills the form and submit.

Create project

  • Method 1. In my home page, click + button create new RAP interface document.
  • Method 2. Click Team in the top menu, create your project under correct Team -> Business Line -> Group

Manage organizations

  1. Click team in top menu, choose your team (Set up by RAP server admin)
  2. Choose your Business Line, you can also create new one.
  3. Choose Group, you can also create new one.

Document Editing

Workspace

After creating project, click project link to enter Interface Document Workspace.

This workspace has two mode:

View Mode(Default):Hide UI for editing, make document be simple to read. When you want to edit, press Edit button on the right top corner.

Edit Mode:Show all UI for editing.

** First time entered, default module/page/actions will be created. Please enjoy change them. **

Structure of interface document

  • Module Every module present for a tab of workspace.
  • Page Every module has multiple pages.
  • Action Every page has multiple actions which presents for an interface.
  • Parameter Every action has multiple parameters, for complex object, parameter may have child parameters.

Save your work

  • Save After finished editing, press Quick Save to submit without comments, or use Save button to submit normally.

  • Version Control RAP supplies method to see or switch between versions.

  • Document Export Export word document(Please change file extensions to *.html on Mac OS)

Front-End MOCK tool

Import RAP plugin

RAP can dynamically generate Mock service by analyzing interface documents. What you need to do is just put one line code into your project. Press Plugin Code to obtain plugin script code.

Pay attention to the script orders, please put RAP plugin script after jQuery/AngularJS/etc to ensure RAP plugin can successfully intercept the base libraries.

Mock Rules

On default, RAP generate default data of parameter definitions, you can also manage Mock rules by adding Mock tags. eg-> you want to add incrementing id field, you can use MockJS grammer:

Variable Name    Remarks
id|+1            @mock=100

// id will start from `100`, step is `1`

Want to know more details of MockJS rules, please visit: MockJS.com.

Mock Tags Details

Show/Hide

By clicking Mock button on the right top corner, you can switch Mock tags visibility. When you just want to handle the document structure, hiding Mock data make document simple to read.

MockJS Rules in RAP

Write @mock tags in remark columns, remarks should be separated with @mock tag by character ;, eg->

There's a parameter called userId, remark is User ID, mock tag is @mock=123, than we can write in this way:

Variable Name       Remark
userId              User Id;@mock=123

Escaptions

Variable Name    Remark                Result
escapeDemo       @mock="123"           "escapeDemo" : "\"123\""
noEscapeDemo     @{mock}="123"       "noEscapeDemo" : ""1,2,3"" // Grammer error!

all @mock value will be escaped on default, if you don't want, please replaced by @{mock}.

Dynamically generate MockJS template by request parameters.

By using grammer like ${page}, RAP will replace this ${page} to the real HTTP parameter value, eg->:

@mock=${page}

If the HTTP parameter page's value is 123, than this will be equal to @mock=123

Caution: if this grammer is used in identifier name, remember don't write @mock=(only used in remark area), eg->

{"arr|10" : []}

This means the length of arr is 10. If this 10 want to be parameterized, than you can write:

"arr|${total}"

When HTTP parameter total's value is 100, this will be equal to arr|100, namely generate 100 elements.

@mock=${page=10}

This means if no parameter page exists in the HTTP request, default value is 10.

Mock plugin

Import the plugin

After jQuery or other libraries, insert:

<script type="text/javascript" src="http://{domain}/rap.plugin.js?projectId={{projectId}}&mode={{mode}}"></script>

In code above:

  • {{projectId}} is project id
  • {{mode}} is plugin working mode, default is 3.

mode value explanations:

  • 0 - no interceptions
  • 1 - all requests will be intercepted.
  • 2 - intercept all requests except ones existing in black list.
  • 3 - (default) intercept all requests existing in white list.

** white list is configured in default, so RAP plugin won't intercept requests not defined in RAP document **

RAP Mock Plugin API

You can manually set up black/white list, set working mode dynamically.

Set blacklist
RAP.setBlackList(arr);
Set whitelist
RAP.setWhiteList(arr);

arrcan contains strings or regular expression objects, eg-> ['test', /test/g]

get current mode
RAP.getMode();
set mode
RAP.setMode(1);

NodeJS Plugin

Link

Back-End tools

How to entered?

Click little icon after page nodes in the left structure tree.

Main functions in control:

  1. Real interface self test
  2. Real interface data stucture validation
  3. Request Loging

Test in automation

RAP has opened APIs for testers create their own tools & scripts.

RAP Short Cuts

  • Alt + F Search
  • Ctrl + Enter Auto Complete Parameter
  • Tab Parameter switch
  • Shift + Tab Parameter switch back forward

Document edit advanced skills

URL grammer

http://www.taobao.com/getItem?[callback]=foo

[callback] is to say that callback will be the JSONP callback key, eg-> getItem?callback=foo, mock request result would be: foo({...});

http://www.taobao.com/getREST?{path}=delete

{path} means the parameter path will be used for action matching, this feature is usually used in RESTful API. eg-> getRest?path=delete, getRest?path=update, than getRest?path=delete matches http://www.taobao.com/getREST?{path}=delete, but won't match http://www.taobao.com/getREST?{path}=update.

Outer structure control

Using statements(@deprecated)

On default, the JSON structure is always {}, not [{}]. If you want the outer structure is array, add this into action descriptions: @type=array_map;@length=1

this means you want the outer structure is array and length is 1.

Using action edit form

When editing detail information on Action Edit Form, there's "Return format" option below. How ever, array length control still need old statments(@length) to fullfill.

RESTful API support

For common RESTful APIs, eg->www.example.com/data/100/query

Please fill action url with:

www.example/data/:id/query

:id here will match any number

For scenes more complex, eg-> www.example.com/biz1432/query, we can use regular expression:

reg:www.example/biz[0-9]{4}/query

Open API

API1:Return RAP project model data. (from project to action)

Path and request parameters

http://{domain}/queryModel.do?projectId={projectId}&ver={ver}
  • {projectId} project id
  • {ver} version number,default is the head version.

Response data structure

Returned object has 3 fields:

  • model - Model data
  • code - error code, return 200 when successful.
  • msg - error message ,return '' when successful.

EXAMPLE

http://rap.domain.com/api/queryModel.do?projectId=423&ver=0.0.0.2

{"model":{"moduleList":[{"id":518,"pageList":[{"id":738,"interfaceList":[{"id":2024,"desc":"","reqUrl":"a","name":"某请求","reqType":"1"},{"id":2025,"desc":"","reqUrl":"bbb","name":"bbb","reqType":"1"}],"name":"某页面","intro":""}],"name":"某模块(点击编辑后双击修改)","intro":""}],"id":429,"name":"临时项目一会儿删掉不要动","ver":"0.0.0.4","intro":""},"code":200,"msg":""}

API2:return detail data of specified action

Path and request parameters

http://{domain}/querySchema.do?actionId={actionId}&ver={ver}&projectId={projectId}&type={type}

其中

  • {actionId} action id
  • {ver}{projectId} optional, when specified, will returned action data in specified versions.
  • {type} optional, "request" stands for request parameters schema, other value or null value presents for response parameters schema.

Response data structure

Object returned has 3 fields:

  • schema - JSON SCHEMA(v4)
  • code - error code
  • msg - error messages

EXAMPLE

http://rap.domain.com/api/querySchema.do?projectId=429&actionId=2024&ver=0.0.0.2

{"schema":{"id":2024,"$schema":"http://json-schema.org/draft-04/schema","properties":{"resParam":{"id":38393,"title":"某响应参数","description":"","format":"MOCKJS||","required":false,"type":"number"},"a":{"id":38392,"title":"","description":"","format":"MOCKJS||","required":false,"type":""}},"required":"false","type":"object"},"code":200,"msg":""}

Common issues

How to share data between different RAP projects?

Use project router, click Config button on right top corner, input project ids you want to share, click confirm button to finish.

eg-> In current project(id=1), I set up router field is "23, 33, 5".

When someone request MOCK service with projectId=1, if no matched action, MOCK service will search projectId=23, projectId=33, projectId=5 in order. If none of these projects matched actions, return "no matched action" error.

How to use RAP plugin in AngularJS?

Thank @goto100 for providing AngularJS RAP Plugin to use RAP mock data: https://github.com/goto100/ng-rap

Any way to let MOCK service returns MockJS data, not MockJS rule templates?

Yes,just replaced /mockjs/ to /mockjsdata/ in MOCK service request urls. eg->

http://{domain}/mockjs/79/rap_mockjs_rules_demo.do?

changed to

http://{domain}/mockjsdata/79/rap_mockjs_rules_demo.do?
Hint:why return mock rule instead of mock data?

In default, RAP service return Mock.js template(rules), if using RAP plugin, it
will convert rules => data for u.

Advantages:
1. Directly show the data how to be generated.
2. Save network bandwidth.
3. More flexible, have a chance to change rules in specific scene.

RAP插件默认发出请求的路径仍然是mockjs,需要在浏览器中执行RAP.setPrefix('/mockjsdata/')这条语句修改路径

升级mockjs

RAP本身自带的mockjs版本过低,不支持中文字符串等新特性,升级方法可以参考这里,还有这里

You can’t perform that action at this time.