Automatically generate DTO code defined in Swagger document

Introduction

This article introduces a project case using TypeScript and Swagger.

Before using REST API, we often define DTO files by looking at Swagger document. You can manually write DTO files, but by using open source, you can automate it You don't need to define coding rules separately, and you can easily change DTO when it changes.

This article introduces how to automatically generate DTO defined in Swagger document and how to bundle routing files for development productivity in large-scale projects.

Automatically generate DTO defined in Swagger document

The DTO of Swagger document can be automatically generated as TypeScript file of the project using swagger-typescript-api. In the early introduction, it was difficult to identify the added/modified DTO because the DTO was managed in a single file and Git diff increased.

You can easily manage files by separating them by using options appropriately. When I used it in the project, I defined it in package.json and used it, and the command and options are as follows.

swagger-typescript-api -p {Swagger JSON address} -o {DTO file path} --no-client --route-types --modular --sort-types

• -p sets the json file address of swagger.
• -o sets the location where the swagger DTO file is stored in the project.
• --no-client prevents JS code that requests API from being generated when running open source.
• --route-types defines API route paths by separating each namespace.
• --modular sets whether to separate the file used in common in the API route from the DTO to the data-contracts.ts file.
• --sort-types defines DTO by sorting.

Bundle routing files

In the field, REST API is different for each service function, and the front-end person in charge is different for each function. In a situation where colleagues use the same repository, common DTO files often cause conflict problems in repository files. Therefore, there are cases where you have to manually resolve conflict problems in code merge or Pull Request.

To solve this problem, we use dts-bundle-generator to bundle DTO files. Bundling works as follows.

// route.ts
import { CommonProps, CommonName } from "./common";

export interface Props extends CommonProps {
    url: string;
    name: CommonName
}

// common.ts
export interface CommonProps {
    description: string;
}
export type CommonName = string;

When you have the above file and run the dts-bundle-generator -o bundle.d.ts ./route.ts command, the bundled file is created as follows.

// Generated by dts-bundle-generator v8.0.1

export interface CommonProps {
  description: string;
}
export type CommonName = string;
export interface Props extends CommonProps {
  url: string;
  name: CommonName;
}

export {};

Conclusion

Finally, TypeScript code generated using open source may differ from the coding rules of the project. This problem can be easily solved by using the eslint or prettier set in the current project when automatically generating the DTO file of Swagger.