docs
中文文档

API Code Generation

Installation

1npm install @clean-js/api-gen

Features

• Generates request code based on API protocols such as YAPI, Swagger 2, and Swagger 3.
• Declares complete TypeScript input and output parameter types.
• Supports path parameter replacement.
• YAPI writes the interface's address in the comments.
• zod support
• Method naming convention is method+url, for example, /user, method: post, and the generated code looks like this:

1/** Yapi link: https://yapi.xxxx.com/project/2055/interface/api/125352 */
2export function postUser(parameter: { body: PostUserBody }) {
3  return Req.request<ResponsePostUser>({
4    url: '/user',
5    method: 'post',
6    data: parameter.body,
7  });
8}

The axios-generated code looks like this:

1export function postDatasetVersionRecords(
2  parameter: {
3    body: any;
4    path: {
5      version: string;
6      dataset: string;
7    };
8  },
9  config?: AxiosRequestConfig,
10) {
11  return Req.request<ResponsePostDatasetVersionRecords>({
12    url: replaceUrlPath('/{dataset}/{version}/records', parameter?.path),
13    method: 'post',
14    data: parameter.body,
15    ...config,
16  });
17}

Configuration

Interface:

1export interface Config {
2  url: string; // HTTP or absolute file path.
3  outDir?: string; // Output file path. Default is ./clean-js.
4  type?: "umi3" | "axios"; // The type of generated code. Umi3 is based on umi-request library, and the default is axios.
5  zod?: boolean; // Whether to enable zod validation for runtime data type checking.
6  mock?: false | {} // generate mock file
7}

Create a new clean.config.ts file:

1export default {
2  url: 'https://petstore3.swagger.io/api/v3/openapi.json', // swagger 3
3  url: 'https://petstore.swagger.io/v2/swagger.json', // swagger 2
4  url: 'http://yapi.smart-xwork.cn/api/open/plugin/export-full?type=json&pid=186904&status=all&token=59ecff7d43926c3be48f893deba401407f0d819c6c24a99b307a78c0877bc7d2' // yapi
5}

YAPI

1. Go to Project -> Settings -> Generate TS Services and copy the remote URL address.
2. Paste the remote URL address into the url field in the clean.config.ts file.
3. Run npm run api-gen.

Swagger

1. Copy the Swagger JSON online address or the absolute file path (relative path).
2. Paste the Swagger JSON address into the url field in the clean.config.ts file.
3. Run npm run api-gen.

Runtime

Set the request instance during runtime:

1import { Req } from '@/clean-js/http.service';
2function initCleanJsApi() {
3  Req.set(request);
4}

Diff

When the document changes, re-running api-gen generates a diff record that shows the number of added, reduced, and changed APIs.

1Date: 2022-11-26 12:26:34
2
3Sum-up: Added 20 APIs Reduce 3 APIs 

Runtime Type Validation

Enabling Zod can be used for type validation of returned data from API to detect issues in production.

To enable Zod, set the zod flag in the configuration file to true.

1export default {
2  ...
3  zod: true
4}

Configure error handling function as follows:

1import { Req } from '@/clean-js/http.service';
2
3Req.setZodErrorHandler((error, value, url, schema ) => {
4    // You can report errors here
5    console.log(error)
6});

mock

By leveraging the functionality of worker-webserver, we can use Service Worker to mock API requests. Here are the specific steps:

1. Install dependencies

   1npm install worker-webserver @anatine/zod-mock @faker-js/faker --save

2. Export the sw.js file using the CLI command and place it in your static resource directory. If you are using Vite or Umi, this corresponds to the public folder:

   1npx worker-webserver --out public

3. Enable the API-gen mock config.

1// ./clean.config.ts
2import { defineConfig } from './src/config';
3
4export default defineConfig({
5  zod: true,
6  url: 'https://petstore3.swagger.io/api/v3/openapi.json', // swagger 3
7  type: 'umi3',
8  mock: {}, // default false
9});
10

1. In your business code, you can use include and exclude to filter the desired routes:

1import { apiRoutes, includePath } from "./api/http.mock"; // Generated file
2let routes = includePath(apiRoutes, ["/api/*"]);
3routes = excludePath(routes, ["/api/test/*"]);

1. Enable the worker server in your business code:

1  import { App, Route } from "worker-webserver";
2  import { apiRoutes, includePath } from "./api/http.mock"; // Generated file
3  
4  function openMock() {
5    const app = new App();
6    app.addRoutes(apiRoutes);
7    
8    // Add middleware to the server, the following functionality is to unify the business code to 200
9    app.use(async (ctx, next) => {
10      await next();
11    
12      // Unify code to 200
13      if (ctx.res.body) {
14        const contentType = ctx.res.headers.get("content-type");
15        if (contentType === "application/json") {
16          try {
17            const body = JSON.parse(ctx.res.body);
18            if (body.code) {
19              body.code = 200;
20            }
21            ctx.res.body = JSON.stringify(body);
22          } catch {}
23        }
24      }
25    });
26    
27    // Start the worker server
28    app.start();
29  }
30

1. If you need to shut down the worker server, execute the following command:

1  app.stop();

This way, you can use Service Worker to mock API requests.