docs
中文文档

API Code Generation

Installation

npm 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:

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

The axios-generated code looks like this:

export function postDatasetVersionRecords(
  parameter: {
    body: any;
    path: {
      version: string;
      dataset: string;
    };
  },
  config?: AxiosRequestConfig,
) {
  return Req.request<ResponsePostDatasetVersionRecords>({
    url: replaceUrlPath('/{dataset}/{version}/records', parameter?.path),
    method: 'post',
    data: parameter.body,
    ...config,
  });
}

Configuration

Interface:

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

Create a new clean.config.ts file:

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

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:

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

Diff

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

Date: 2022-11-26 12:26:34

Sum-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.

export default {
  ...
  zod: true
}

Configure error handling function as follows:

import { Req } from '@/clean-js/http.service';

Req.setZodErrorHandler((error, value, url, schema ) => {
    // You can report errors here
    console.log(error)
});

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

   npm 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:

   npx worker-webserver --out public

3. Enable the API-gen mock config.

// ./clean.config.ts
import { defineConfig } from './src/config';

export default defineConfig({
  zod: true,
  url: 'https://petstore3.swagger.io/api/v3/openapi.json', // swagger 3
  type: 'umi3',
  mock: {}, // default false
});

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

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

1. Enable the worker server in your business code:

  import { App, Route } from "worker-webserver";
  import { apiRoutes, includePath } from "./api/http.mock"; // Generated file
  
  function openMock() {
    const app = new App();
    app.addRoutes(apiRoutes);
    
    // Add middleware to the server, the following functionality is to unify the business code to 200
    app.use(async (ctx, next) => {
      await next();
    
      // Unify code to 200
      if (ctx.res.body) {
        const contentType = ctx.res.headers.get("content-type");
        if (contentType === "application/json") {
          try {
            const body = JSON.parse(ctx.res.body);
            if (body.code) {
              body.code = 200;
            }
            ctx.res.body = JSON.stringify(body);
          } catch {}
        }
      }
    });
    
    // Start the worker server
    app.start();
  }

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

  app.stop();

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