preface

TypeScript + React type security is a three-piece package: Component, Redux, and Service typing.

Service typed

Common base solution

Specifications and base types

For example, all interfaces should return data in the following format:

interface AjaxResult<R extends any> {
    /** Error code */code? :number | null;
    /** Description */message? :string | null;
    /** Data subject */
    result: R
}
Copy the code

Instead, all interface-calling functions should follow this interface definition:

interfaceAjaxFunction { (... args:any[]) :Promise<AjaxResult<any>>
}
Copy the code

What needs to be clear in the business logic is the type of the parameters and response data body to be put into the interface definition.

The sample

Take an example of an interface to get user information, via any format documentation provided on the back end, such as Swagger, YAPI, or even wiki:

  • The url is/api/user/info
  • You need to pass a get parameter of numeric typeid
  • The returned data body is an object containing the numeric ID and the string name

Write TypeScript calling code:

/** Back-end data body */
interface UserResult {
    /** id */
    id: number;
    /** English name */
    name: string;
}

/** Interface call code */
const getUserInfo = (id: number): AjaxResult<UserResult> => axios.get('/api/user/info', { id })
Copy the code

Sm2tsservice solution 【will be@tefe/service】

From the previous example, we can see that the real pain point of Service typing is writing TypeScript code based on the interface document. When the data is formatted from an existing Swagger or YAPI document, this is a waste of repetitive labor. Finding a technical solution to automate the generation will greatly improve the development efficiency.

swagger-codegen

Swagger’s Swagger system, which extracts documents based on Java code annotations, includes swagger-CodeGen, which provides a full suite of Java annotations, annotation parsing, document UI interfaces, and technical tools for generating code calls in various languages.

The solution supports the generation of TypeScript types and interface invocation code. The core data conversion and generation rules are as follows:

Based on the above rules, it is easy to find that the scheme has the following hidden dangers:

  • Tags annotation is not empty, change annotation or annotation is empty, change Controller Name, will cause Tags value change, resulting in the generated file Name change;
  • The API annotation is not empty, the annotation is repeated or the annotation is empty, and the Method Name is repeated. When the order of the repeated Method Name changes, the value of operationId will change.
  • When the order of Method parameters is changed, the parameters of the corresponding interface calling code are changed.

These pitfalls can lead to uncontrolled changes in the generated code when certain conditions are met, leading to logic confusion, with very serious consequences.

sm2tsservice

Sm2tsservice takes Swagger-CodeGen and encapsulates it to address the pain points of business use:

  • Implement yAPI swagger documentation module, support YAPI automatically generate interface call code
  • Develop Swagger documentation specifications to improve front and back end collaboration
  • Swagger document specification verification and rule correction modules are implemented to ensure the stability of generated code
  • Swagger Document incremental update module for more flexible control of code generation
  • Implement interface input parameters, data return verification module, using Swagger documents for data verification
Yapi swagger rules

To convert a YAPI document to a Swagger document, the curve allows YAPI to automatically generate service code by the following rules:

Swagger Documentation specification

Interface specification, designed to eliminate artificial uncertainty, the core items include:

Swagger Calibration, calibration module

To verify that a Swagger document conforms to the specification and to calibrate how operationId is generated, the core rules are as follows:

To customize the Swagger-CodeGen code, modify the calling function format:

Incremental updating

Interface documents are divided into local and remote versions. The local version is maintained with the VCS. Each time the code is generated, the remote version will be downloaded, and then diff with the local version to display the differences in the form of web interface for arbitrary differences and incremental updates:

Double check

Provides a proxy plug-in for interface inputs and back-end returns during the debugging phase, verifying against the corresponding Swagger document conventions, and printing out non-conforming interface errors by default.

More

  • Sm2tsservive document station
  • Incremental update technology solution jSON-diff
  • Code generation scheme custom Swagger-CodeGen