---
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`配置文件：

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

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

<Props of={IJSON2Service} />

## 2.2.1 yapiConfig 参数

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

<Props of={IYAPIConfig} />

## 2.2.2 swaggerParser 参数

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

<Props of={ISwaggerParser} />

## 2.2.3 guardConfig 参数

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

<Props of={IGuardConfig} />

## 2.2.4 requestConfig 参数

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

<Props of={IRequest} />

## 2.2.5 swaggerConfig 参数

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

<Props of={ISwaggerConfig} />

## 2.2.6 示例

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

```json
{
  "url": "./api.json", // 文件路径
  "remoteUrl": "http://**", // 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 生成目标代码：

```shell
  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 内添加：

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

`npm run api` 生成目标代码。

## 3. Ajax 接口

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

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

你可以参考 [@ekit/ajax](https://github.com/e-kit/ekit/blob/master/packages/ajax/src/new-ajax.ts) 代码实现自定义的 `@ajax` 模块，或者按照以下接口定义，实现自定义的 `@ajax` 模块：

```ts
/** 不再兼容非标准的数据结构 */
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 代码，如以下示例所示：

```ts
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`，如以下示例所示：

```ts
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 到最新的版本）：

```ts
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';

<CHANGELOG />