增加api doc模块

package.json

@@ -20,6 +20,7 @@
     "dva-loading": "^1.0.4",
     "fastjson_ref_resolver": "latest",
     "fingerprintjs": "^0.5.3",
+    "github-markdown-css": "^2.10.0",
     "history": "latest",
     "is-promise": "^2.1.0",
     "lodash": "^4.17.4",
@@ -30,6 +31,7 @@
     "react-async-wrapper": "^0.0.7",
     "react-dom": "^16.2.0",
     "react-json-view": "^1.11.4",
+    "react-markdown": "^3.3.0",
     "react-router-4-compat": "^0.1.4",
     "resolve-pathname": "^2.1.0",
     "uuid": "^3.1.0",
@@ -62,6 +64,7 @@
     "markdown-loader": "^2.0.2",
     "mockjs": "^1.0.1-beta3",
     "path": "^0.12.7",
+    "raw-loader": "^0.5.1",
     "react-test-renderer": "^16.2.0",
     "redbox-react": "^1.5.0",
     "roadhog": "^2.3.0-beta.1"

src/components/hoc/routes.js

@@ -5,7 +5,6 @@ const route = (routes) => {
     return children || null;
   };
   Wrapper.route = {
-    ...routes,
     indexRoute: {
       onEnter(nextState, replace) {
         if (routes && routes.childRoutes && routes.childRoutes.length > 0) {
@@ -14,6 +13,7 @@ const route = (routes) => {
         }
       },
     },
+    ...routes,
   };
   return Wrapper;
 };

src/index.css

 @charset "utf-8";
-* {
+/** {
   margin: 0;
   padding: 0;
-}
+}*/
 
 html {
   color: #000;
   background: #FFF;
   height: 100%;
+  width: 100%;
+  margin: 0;
+  padding: 0;
 }
 
 body {
   height: 100%;
+  width: 100%;
+  margin: 0;
+  padding: 0;
 }
 
-body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, form,
+/*body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, form,
 fieldset, input, textarea, p, blockquote, th, td {
   margin: 0;
   padding: 0;
@@ -61,11 +67,12 @@ li {
 
 input, img {
   border: none;
-}
+}*/
 
 :global(#root) {
   margin: 0;
   padding: 0;
   height: 100%;
+  width: 100%;
 }
 

src/models/main/modules/api-doc/index.js

+export default {
+  namespace: 'apiDoc',
+  state: {},
+  reducers: {},
+  effects: {},
+  subscriptions: {},
+};

src/register/modules/empty.js

 /* eslint-disable */
-export default [/*{
+export default [{
   name: 'test-menu',
   showName: '测试',
   modules: [{
     name: 'test-module',
     showName: '测试',
     layout: {
-      route: 'task',
+      route: 'api-doc',
     },
   }],
-}*/];
+}];

src/routes/main/modules/api-doc/MarkDown.js

+/* eslint-disable react/no-danger */
+import React from 'react';
+import PropTypes from 'prop-types';
+
+class MarkDown extends React.Component {
+  render() {
+    return (
+      <div dangerouslySetInnerHTML={{
+        __html: this.props.markdown,
+      }}
+      />
+    );
+  }
+}
+
+MarkDown.propTypes = {
+  markdown: PropTypes.string,
+};
+
+MarkDown.defaultProps = {
+  markdown: '',
+};
+
+export default MarkDown;

src/routes/main/modules/api-doc/auth.md

+# 登录与认证
+
+登录分为2个步骤。
+第一步通过用户名或其他用户标识符确定用户的存在性，
+并获得一个未认证的token（令牌）。
+同时返回的还有该用户需要经过哪些认证方式才能真正登录。
+第二步使用上一步获得的令牌，并根据给予的验证需求，使用对应的方式予以认证。
+所有验证需求都验证通过后，才正式登录成功，并且token变为有效。
+之后所有的api调用都会用到此token。
+
+## 获取一个未验证token
+
+- **URL**:
+/api/auth/login
+
+- **Method**:
+POST
+
+- **Accept**: application/json
+
+  ```
+  {
+    type: string, //登录方式
+    data: string, //登录方式对应的登录数据
+    tokenInfo: { //令牌信息
+      productId: string, //产品ID
+      deviceId: string //设备ID
+    },
+    authRequest: { //验证请求，可选
+      type: string, //验证方式
+      parameters: Map //验证参数
+    }
+  }
+  ```
+
+  > - *type*: 登录方式, 可选值为`userName`，`email`，分别表示用户名登录和邮箱登录。
+  > - *data*: 登录方式对应的登录数据, `userName`对应的登录数据即为用户名，`email`对应的登录数据即为邮箱地址
+  > - *tokenInfo*: 登录必备的信息，为权限验证所需。
+  >   - *productId*: 产品ID，表示要登录的产品。
+  >   - *deviceId*: 设备ID，一条可以用来唯一标识客户端的字符串，生成规则不限，只要保证唯一性和不变性即可。
+  > - *authRequest*: 验证请求，为了简化接口，登录的同时也可以一起进行验证。
+      前提是事先知道对应用户需要用哪种方式进行验证。因为用户所需的验证方式是后台可配置，
+      不是一成不变的，所以不建议登录验证同时进行的api调用方式。
+  >   - *type*: 验证方式。可选值为`password`，表示密码登录
+  >   - *parameters*: 验证参数。`password`对应的验证参数为
+      `{ cipher: string }`，表示用户密码。
+    
+- **Content-Type**:
+application/json
+
+  ```
+  {
+    tokenId: string,
+    authResponse: {
+      type: string,
+      status: string,
+      data: any,
+      remainedAuthRequirements: {
+        requirements: [{
+          authTypes: [string]
+        }]
+      }
+    },
+    remainedAuthRequirements: {  
+      requirements: [{
+        authTypes: [string]
+      }]
+    }
+  }
+  ```
+  > - *tokenId*: 未加密的原始token字符串，该token在服务器存在内存中，
+      若超过30分钟没有使用该token，该token将失效。
+  > - *authResponse*: 验证响应，请求体中包含`authRequest`字段时，响应体中才会有此字段。
+      - *type*: 验证类型，与请求体中`authRequest.type`值相同。
+      - *status*: 验证状态，可能值为：`authed`,`rejected`,`skipped`等。
+        `authed`表示验证通过，`rejected`表示验证未通过，`skipped`表示不需要此步验证。
+        以上3种可能值为所有验证方式共有。其他可能值依赖于各自的验证方式。
+      - *data*: 验证响应数据。其含义依赖于验证方式。
+      - *remainedAuthRequirements*: 剩余的验证需求。
+        - *requirements*: 若干个验证需求，逻辑关系为和。
+          若为空数组，表示所有验证需求均已满足，即全部验证成功。
+          - *authTypes*: 若干个验证方式，逻辑关系为或，
+            只要其中一个验证方式验证成功，该验证条件即满足。
+  > - *remainedAuthRequirements*: 同`authResponse.remainedAuthRequirements`。
+      不同之处在于请求体中不需要包含`authRequest`，该字段也存在。
+- **note**:
+
+  获取后的token，不能直接使用，需要使用公钥进行非对称加密。加密方式如下：
+  1. 直接使用token，或包装成令牌对象：
+     ```
+     {
+       tkId: string, //令牌
+       ett: long, //令牌发出时间，从1970/1/1 UTC至今的毫秒数
+       life: long //令牌对象有效期，单位毫秒
+     }
+     ```
+  2. 将token字符串本身或包装成的令牌对象的json字符串表示转为utf-8字节数组。
+  3. 使用给定公钥，以**RSA/None/PKCS1Padding**方式进行加密。然后对加密结果进行base64urlsafing方式转码
+     （先进行普通的base64转码，然后去除尾部'='，然后用'-'替换所有'+'，用'_'替换所有'/'）
+- **公钥**:
+ 
+  `-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+/Rs6dYmdtETjHCZq4LF3QjLM/DocRAXrqtMULZf+579dAn+CiM8noLplZT/DRwvfK822eq8sypH+a4NqP7942pPVjOudVvKfiJvmm2TOQHvQ7vi3iyZVdlsxX72JNFo1Ocqwj48aIC/OJ4bMf/VyCKrmKrU2iXND+I4BN8cfhwIDAQAB-----END PUBLIC KEY-----`
+
+## 验证token
+
+- **URL**:
+/api/auth/authorize
+
+- **Method**:
+POST
+
+- **Accept**:
+application/json
+
+  ```
+  {
+    tkId: string,
+    request: {
+      type: string, //验证方式
+      parameters: Map //验证参数
+    }
+  }
+  ```
+  - *tkId*: 加密后的令牌
+  - *request*: 验证请求
+     - *type*: 验证方式。可选值为`password`，表示密码登录
+     - *parameters*: 验证参数。`password`对应的验证参数为
+        `{ cipher: string }`，表示用户密码。
+
+- **Content-Type**:
+application/json
+
+  ```
+  {
+    type: string,
+    status: string,
+    data: any,
+    remainedAuthRequirements: {
+      requirements: [{
+        authTypes: [string]
+      }]
+    }
+  }
+  ```
+  - *type*: 验证类型，与请求体中`authRequest.type`值相同。
+  - *status*: 验证状态，可能值为：`authed`,`rejected`,`skipped`等。
+    `authed`表示验证通过，`rejected`表示验证未通过，`skipped`表示不需要此步验证。
+    以上3种可能值为所有验证方式共有。其他可能值依赖于各自的验证方式。
+  - *data*: 验证响应数据。其含义依赖于验证方式。
+  - *remainedAuthRequirements*: 剩余的验证需求。
+    - *requirements*: 若干个验证需求，逻辑关系为和。
+      若为空数组，表示所有验证需求均已满足，即全部验证成功。
+      - *authTypes*: 若干个验证方式，逻辑关系为或，
+        只要其中一个验证方式验证成功，该验证条件即满足。
+        
+## 登出
+
+- **URL**:
+/api/auth/logout
+
+- **Method**:
+POST
+
+- **Accept**:
+application/json
+  `empty` (只包含前置说明中提到的token，即`{ token: string }`， 之后不再重复说明。)
+
+- **Content-Type**: 
+application/json
+  `null` (并不是真正的空，仅仅是如前置说明中提到那样，`data`字段为`null`， 之后不再重复说明。)

src/routes/main/modules/api-doc/default.less

+.markdown {
+  overflow-y: scroll;
+  -webkit-text-size-adjust: 100%;
+  -ms-text-size-adjust: 100%;
+
+  width: 100%;
+  color:#444;
+  font-family:Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
+  font-size:12px;
+  line-height:1.5em;
+  padding:1em;
+  background:#fefefe;
+
+  a{ color: #0645ad; text-decoration:none;}
+  a:visited{ color: #0b0080; }
+  a:hover{ color: #06e; }
+  a:active{ color:#faa700; }
+  a:focus{ outline: thin dotted; }
+  a:hover, a:active{ outline: 0; }
+
+  ::-moz-selection{background:rgba(255,255,0,0.3);color:#000}
+  ::selection{background:rgba(255,255,0,0.3);color:#000}
+
+  a::-moz-selection{background:rgba(255,255,0,0.3);color:#0645ad}
+  a::selection{background:rgba(255,255,0,0.3);color:#0645ad}
+
+  p{
+    margin:1em 0;
+  }
+
+  img{
+    max-width:100%;
+  }
+
+  h1,h2,h3,h4,h5,h6{
+    font-weight:normal;
+    color:#111;
+    line-height:1em;
+  }
+  h4,h5,h6{ font-weight: bold; }
+  h1{ font-size:2.5em; }
+  h2{ font-size:2em; }
+  h3{ font-size:1.5em; }
+  h4{ font-size:1.2em; }
+  h5{ font-size:1em; }
+  h6{ font-size:0.9em; }
+
+  blockquote{
+    color:#666666;
+    margin:0;
+    padding-left: 3em;
+    border-left: 0.5em #EEE solid;
+  }
+  hr { display: block; height: 2px; border: 0; border-top: 1px solid #aaa;border-bottom: 1px solid #eee; margin: 1em 0; padding: 0; }
+  pre, code, kbd, samp { color: #000; font-family: monospace, monospace; _font-family: 'courier new', monospace; font-size: 0.98em; }
+  pre { white-space: pre; white-space: pre-wrap; word-wrap: break-word; }
+
+  b, strong { font-weight: bold; }
+
+  dfn { font-style: italic; }
+
+  ins { background: #ff9; color: #000; text-decoration: none; }
+
+  mark { background: #ff0; color: #000; font-style: italic; font-weight: bold; }
+
+  sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
+  sup { top: -0.5em; }
+  sub { bottom: -0.25em; }
+
+  ul, ol { margin: 1em 0; padding: 0 0 0 2em; }
+  li p:last-child { margin:0 }
+  dd { margin: 0 0 0 2em; }
+
+  img { border: 0; -ms-interpolation-mode: bicubic; vertical-align: middle; }
+
+  table {
+    border-collapse: collapse;
+    border-spacing: 0;
+    width: 100%;
+  }
+  th { border-bottom: 1px solid black; }
+  td { vertical-align: top; }
+
+  @media only screen and (min-width: 480px) {
+    font-size:14px;
+  }
+
+  @media only screen and (min-width: 768px) {
+    font-size:16px;
+  }
+
+  @media print {
+    * { background: transparent !important; color: black !important; filter:none !important; -ms-filter: none !important; }
+    font-size:12pt; max-width:100%;
+
+    a, a:visited { text-decoration: underline; }
+    hr { height: 1px; border:0; border-bottom:1px solid black; }
+    a[href]:after { content: " (" attr(href) ")"; }
+    abbr[title]:after { content: " (" attr(title) ")"; }
+    .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { content: ""; }
+    pre, blockquote { border: 1px solid #999; padding-right: 1em; page-break-inside: avoid; }
+    tr, img { page-break-inside: avoid; }
+    img { max-width: 100% !important; }
+    @page :left { margin: 15mm 20mm 15mm 10mm; }
+    @page :right { margin: 15mm 10mm 15mm 20mm; }
+    p, h2, h3 { orphans: 3; widows: 3; }
+    h2, h3 { page-break-after: avoid; }
+  }
+}

src/routes/main/modules/api-doc/index.js

+import React from 'react';
+import { connect } from 'dva';
+import ReactMarkdown from 'react-markdown';
+import 'github-markdown-css';
+import mdIndex from './index.md';
+import mdAuth from './auth.md';
+import route from '../../../../components/hoc/routes';
+
+const md = mdString => () => <ReactMarkdown className="markdown-body" source={mdString} />;
+
+export default connect(({ apiDoc }) => ({ apiDoc }))(route({
+  indexRoute: {
+    component: md(mdIndex),
+  },
+  childRoutes: [
+    {
+      path: 'auth',
+      name: '登录与验证',
+      component: md(mdAuth),
+    },
+  ],
+}));

src/routes/main/modules/api-doc/index.md

+# API Document
+
+# 前置说明
+
+1. 接口的返回基本都是json格式，并且有如下形式: 
+   ```
+   {
+     errorCode: long,
+     data: any,
+     message: string
+   }
+   ```
+   > - *errorCode*: 错误码，0表示成功，无错误
+   > - *data*: 真正的返回数据，后续文档如无特别说明，对于返回形式的描述都是指的data的格式。
+               另外，发生错误时，这个字段也可能保护错误相关信息。
+   > - *message*: 错误消息，`errorCode`为0时，不使用这个字段。
+
+2. 除了登录接口（获取token的接口），所有其他接口都要使用令牌（token）进行权限验证。
+   token使用方式目前统一为: 
+   - 若为GET或DELETE方法接口，token加密后作为query参数拼接在url上，参数名为token。
+   - 若为POST方法接口，并且请求体是json格式的，若无特别说明，都保护一个token属性，值为加密后的token。
+   - token的加密方式在登录部分会提及。
+
+3. 服务端使用fastjson进行json的解析，
+   该框架支持循环引用的json序列化，
+   并且对于json树中的同一个引用，
+   可能会使用特殊的表示方式。具体见[循环引用](https://github.com/alibaba/fastjson/wiki/%E5%BE%AA%E7%8E%AF%E5%BC%95%E7%94%A8)。
+   所以返回的json数据里部分属性可能以引用的形式存在。需要进一步解析。
+   若使用java，可以用fastjson的[JSONPath](https://github.com/alibaba/fastjson/wiki/JSONPath)来进行解析。
+   若使用javascript，可以用npm上的一个库[fastjson_ref_resolver](https://www.npmjs.com/package/fastjson_ref_resolver)来进一步处理。
+
+## 目录
+
+- [登录与验证](auth)

webpack.config.js

@@ -43,16 +43,23 @@ function pickDeep(collection, ...args) {
 module.exports = function webpack(config) {
   config.module.rules.push({
     test: /\.ejs$/,
-    loader: 'ejs-loader',
+    loader: require.resolve('ejs-loader'),
+  });
+  config.module.rules = config.module.rules.map((rule) => {
+    if (!rule.test && rule.exclude) {
+      rule.exclude = [...rule.exclude, /\.md$/];
+    }
+    return rule;
   });
   config.module.rules.push({
     test: /\.md$/,
     use: [
-      'html-loader',
-      'highlight-loader',
-      'markdown-loader',
+      // require.resolve('html-loader'),
+      // require.resolve('highlight-loader'),
+      require.resolve('raw-loader'),
     ],
   });
+  // console.log(config.module.rules);
   let cleanedConfig = omit(config, 'plugins');
   cleanedConfig.resolve = omit(cleanedConfig.resolve, 'plugins');
   cleanedConfig = pickDeep(cleanedConfig, v => !isFunction(v) && !isUndefined(v));