name	route
快速上手	/getting-started

import { Props } from 'docz'; import { IGuardConfig, IYAPIConfig, ISwaggerParser, IJSON2Service, IRequest, ISwaggerConfig } from './tests/Doc.tsx';

API

1. 安装 Autos

通过 npm 安装 Autos。

$ npm i -D auto-service
$ npx autos --help
$ npx autos --init # 快速的创建`json2service.js`配置文件：

2. 参数配置

2.1 命令行参数

以下可直接通过命令行设置的参数：

  -V, --version                  output the version number
  -c, --config [path]            config file (default: "json2service.json" or "json2service.js")
  --clear                        rm typescript service before gen
  --quiet                        auto merge without popup
  --apis [boolean]               是否生成 apis，如果未指定 models 且未指定 typeScriptDataFile 则会生成 apis
  --models [boolean]             是否生成 models，如果未指定 apis 且未指定 typeScriptDataFile 则会生成 models
  --typeScriptDataFile [string]  是否仅生成 TypeScript Data，可用于完全自定义生成逻辑
  --init [string]                在当前目录下创建配置文件，默认是 json2service.js
  -h, --help                     output usage information

2.2 主配置文件

Autos 默认从当前目录下的 json2service.json 文件读取主配置，我们也可以通过命令行参数 -c, --config 指定任意格式为 JSON 或者 JavaScript 的配置文件。

我们可以使用npx autos --init命令快速的创建一个json2service.js配置文件：

  npx autos --init
  prompt: 请选择接口文档类型 type，yapi 或者 swagger:
  prompt: 请输入接口文档源地址 remoteUrl，例如 https://yapi.com/api.json:
  prompt: 请输入接口文档本地存储地址 url，例如：./swagger.json:
  prompt: 请输入 service 代码输出目录 -o，例如: src/services:

配置文件必须导出一个对象，包含以下可配置属性：

2.2.1 yapiConfig 参数

yapiConfig 用以配置将 YApi 格式接口文档转换成 Swagger 接口文档格式的各种规则。

2.2.2 swaggerParser 参数

swaggerParser 用以配置直接透传给 Swagger Codegen Java 生成工具的各种参数。

2.2.3 guardConfig 参数

guardConfig 用以配置检查接口文档是否符合规范的各种规则。

2.2.4 requestConfig 参数

requestConfig 用以配置，当需要使用 http 请求从服务器侧下载接口文档文件时的各种参数。

2.2.5 swaggerConfig 参数

swaggerConfig 用以配置在 Swagger 将被 Swagger Codegen 转换为目标代码前的各种修改器。

2.2.6 示例

以下是一个完整的主配置示例。

{
  "url": "./api.json", // 文件路径
  "remoteUrl": "http:https://**", // url
  "requestConfig": {
    "url": "./api.json" // 文件路径或url
    // 以下所有 request 支持的参数
    // headers?: Headers;
    // baseUrl?: string;
    // callback?: RequestCallback;
    // jar?: CookieJar | boolean;
    // formData?: { [key: string]: any };
    // form?: { [key: string]: any } | string;
    // auth?: AuthOptions;
    // oauth?: OAuthOptions;
    // aws?: AWSOptions;
    // hawk?: HawkOptions;
    // qs?: any;
    // qsStringifyOptions?: any;
    // qsParseOptions?: any;
    // json?: any;
    // jsonReviver?: (key: string, value: any) => any;
    // jsonReplacer?: (key: string, value: any) => any;
    // multipart?: RequestPart[] | Multipart;
    // agent?: http.Agent | https.Agent;
    // agentOptions?: http.AgentOptions | https.AgentOptions;
    // agentClass?: any;
    // forever?: any;
    // host?: string;
    // port?: number;
    // method?: string;
    // body?: any;
    // family?: 4 | 6;
    // followRedirect?: boolean | ((response: http.IncomingMessage) => boolean);
    // followAllRedirects?: boolean;
    // followOriginalHttpMethod?: boolean;
    // maxRedirects?: number;
    // removeRefererHeader?: boolean;
    // encoding?: string | null;
    // pool?: any;
    // timeout?: number;
    // localAddress?: string;
    // proxy?: any;
    // tunnel?: boolean;
    // strictSSL?: boolean;
    // rejectUnauthorized?: boolean;
    // time?: boolean;
    // gzip?: boolean;
    // preambleCRLF?: boolean;
    // postambleCRLF?: boolean;
    // withCredentials?: boolean;
    // key?: Buffer;
    // cert?: Buffer;
    // passphrase?: string;
    // ca?: string | Buffer | string[] | Buffer[];
    // har?: HttpArchiveRequest;
    // useQuerystring?: boolean;
  },
  "type": "yapi",
  "yapiConfig": {
    "required": false,
    "bodyJsonRequired": false,
    "categoryMap": {
      "中文": "English" // yapi 接口分类中英文映射
    }
  },
  "swaggerParser": {
    "-o": "tmp/services"
  },
  "validateResponse": false, // 是否生成校验逻辑
  "guardConfig": {
    // + strict 严格模式
    //    - 校验 swagger tags【yapi 接口分类】是否是纯英文
    //    - 方法名使用 http method + url 驼峰形式
    //    - 新项目采用
    // + safe 安全模式
    //    - 方法名使用 http method + url 驼峰形式
    //    - 老项目升级，不会校验 tags，会生成方法调用替换映射表
    // + 默认
    //    - http method + url => operationId 映射锁定
    //    - 老项目维持现状
    "mode": "strict",
    // swagger 处理重复 operationId 逻辑有风险，因此需要锁定映射关系
    "methodUrl2OperationIdMap": {
      "get /api/xxx/xxx": "operationId"
    }
  }
}

2.3 使用方式

npx

安装 npx npm i -g npx，通过 npx 直接使用 Autos 生成目标代码：

  npx autos # 使用默认配置
  npx autos -c config.json # 指定配置文件
  npx autos --clear # 清空上次生成产物
  npx autos --quiet # 自动全量使用远程文档，不显示 diff & merge 页面
  npx autos --models # 仅生成 models
  npx autos --models --apis # 仅生成 models & apis
  npx autos --typeScriptDataFile TypeSciptData.json # 仅生成类型信息 json 到 TypeSciptData.json

npm scripts

通过 npm scripts 使用 Autos 生成目标代码，在 package.json 内添加：

{
  "scripts": {
    "api": "autos --clear"
  }
}

npm run api 生成目标代码。

3. Ajax 接口

Autos 生成的 Service 代码内包含以下和后端进行通信的固定代码：

import ajax, { AjaxPromise, ExtraFetchParams } from '@ajax';

你可以参考 @ekit/ajax 代码实现自定义的 @ajax 模块，或者按照以下接口定义，实现自定义的 @ajax 模块：

/** 不再兼容非标准的数据结构 */
export declare type AjaxPromise<R> = Promise<R>;
/** 非标准包裹 */
export declare type NonStandardAjaxPromise<R> = Promise<{
  code?: number;
  message?: string;
  result: R;
}>;
export interface ExtraFetchParams {
  /** extra data for extends */
  extra?: any;
  /** 扩展请求头 */
  headers?: any;
  /** cancel request */
  cancel?: Promise<string | undefined>;
}
export interface WrappedFetchParams extends ExtraFetchParams {
  /** http method */
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'PATCH' | 'HEAD';
  url: string;
  /** post json data */
  data?: any;
  /** post form data */
  form?: any;
  /** query data */
  query?: any;
  /** header */
  header?: any;
  /** path data */
  path?: any;
}
export declare class Ajax {
  /** ajax 方法 */
  ajax(
    { method, url, data, form, query, header, extra, cancel, headers }: WrappedFetchParams,
    path?: string,
    basePath?: string
  ): Promise<any>;
  /** 接口传参校验 */
  check<V>(value: V, name: string): void;
  /** 新 fetch 接口，>= 3.5.4 */
  public autosFetch<S extends keyof AutosAPIS>(
    source: S,
    ...args: AutosAPIS[S][0]
  ): Promise<AutosAPIS[S][1]> {
    const { isFile, opt, ...config } = (args[0] || {}) as AutosParams;
    let { headers = {} } = opt || {};
    if (isFile) {
      headers = {
        ...headers,
        'Content-Type': 'multipart/form-data'
      };
    }
    const [method, url] = source.split(' ') as [WrappedFetchParams['method'], string];
    return this.ajax({
      ...config,
      ...opt,
      method,
      url: config.path
        ? url.replace(
            /(({[^}]+})|(:[^/:]+$)|(:[^:/]+))/g,
            all => config.path![all.replace(/[:{}]/g, '')] || ''
          )
        : url,
      headers
    });
  }
}
declare const _default: Ajax;
export default _default;

4. 增量更新

Autos 支持交互勾选界面、增量同步远程增、删、改差异到本地文档。

流程步骤

主配置文件配置 url 和 remoteUrl
- url - 本地接口文档文件路径【如文件不存在，在获取 remoteUrl 指定地址内容后，创建该文件】
- remoteUrl - 新版接口文档 url 或者路径
执行 Autos
Autos 对本地接口文档文件和新版接口文档进行 diff
- 有差异
  - 打开浏览器，人工选择需要同步的差异，点击“保存”
  - Autos patch Delta 生成同步差异后的接口文档
  - 进入下一步
- 无差异
  - 直接进入下一步
Autos 调用 Swagger Codegen 生成目标代码

5. 简洁模式

从 3.5.4 版本起，当配置 swaggerParser['-t'] 参数为 'plugins/typescript-tkit-autos' 时，Autos 会生成通过 url 调用的类型安全的 service 代码，如以下示例所示：

import { ExtraFetchParams } from '@ajax';
import * as models from '../model/models';

declare global {
  interface AutosAPIS {
    'GET /ts-boilerplate/api/user/info': [
      (
        | []
        | [
            {
              opt?: ExtraFetchParams;
            }
          ]
      ),
      models.UserInfo
    ];
  }
}

此时，我们需要使用新版的框架配套的 ajax 或者自行实现 autosFetch，如以下示例所示：

declare global {
  interface AutosAPIS {
    /** 测试接口 */
    'DEMO /ajax/test': [[{}], {}];
  }
}
// ...
function autosFetch<S extends keyof AutosAPIS>(
  source: S,
  ...args: AutosAPIS[S][0]
): Promise<AutosAPIS[S][1]> {
  const { isFile, opt, ...config } = (args[0] || {}) as AutosParams;
  let { headers = {} } = opt || {};
  if (isFile) {
    headers = {
      ...headers,
      'Content-Type': 'multipart/form-data'
    };
  }
  // ...
}

如此，我们就可以直接通过 url 调用 service 代码，如以下示例所示（tCall 需要更新 redux-model 到最新的版本）：

function* test() {
  const data = autosFetch('POST /ts-boilerplate/api/download');
  const res: AutosAPIS['POST /ts-boilerplate/api/download'][1] = yield tCall(
    autosFetch,
    'POST /ts-boilerplate/api/download'
  );
}

6. CHANGELOG

import CHANGELOG from './CHANGELOG.md';

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GettingStarted.mdx

GettingStarted.mdx

API

1. 安装 Autos

2. 参数配置

2.1 命令行参数

2.2 主配置文件

2.2.1 yapiConfig 参数

2.2.2 swaggerParser 参数

2.2.3 guardConfig 参数

2.2.4 requestConfig 参数

2.2.5 swaggerConfig 参数

2.2.6 示例

2.3 使用方式

npx

npm scripts

3. Ajax 接口

4. 增量更新

流程步骤

5. 简洁模式

6. CHANGELOG

Files

GettingStarted.mdx

Latest commit

History

GettingStarted.mdx

File metadata and controls

API

1. 安装 Autos

2. 参数配置

2.1 命令行参数

2.2 主配置文件

2.2.1 yapiConfig 参数

2.2.2 swaggerParser 参数

2.2.3 guardConfig 参数

2.2.4 requestConfig 参数

2.2.5 swaggerConfig 参数

2.2.6 示例

2.3 使用方式

npx

npm scripts

3. Ajax 接口

4. 增量更新

流程步骤

5. 简洁模式

6. CHANGELOG