UNPKG

@nestia/sdk

Version:

Nestia SDK and Swagger generator

246 lines (245 loc) 8.87 kB
import type { INestApplication } from "@nestjs/common"; import type { OpenApi } from "@samchon/openapi"; /** * Definition for the `nestia.config.ts` file. * * @author Jeongho Nam - https://github.com/samchon */ export interface INestiaConfig { /** * Accessor of controller classes. * * You can specify target controller classes within two ways. * * - Asynchronous function returning `INestApplication` instance * - Specify the path or directory of controller class files */ input: (() => Promise<INestApplication>) | INestiaConfig.IInput | string[] | string; /** * Building `swagger.json` is also possible. * * If not specified, you can't build the `swagger.json`. */ swagger?: INestiaConfig.ISwaggerConfig; /** * Output directory that SDK would be placed in. * * If not configured, you can't build the SDK library. */ output?: string; /** * Target directory that SDK distribution files would be placed in. * * If you configure this property and runs `npx nestia sdk` command, * distribution environments for the SDK library would be generated. * * After the SDK library generation, move to the `distribute` directory, * and runs `npm publish` command, then you can share SDK library with * other client (frontend) developers. * * Recommend to use `"packages/api"` value. */ distribute?: string; /** * Allow simulation mode. * * If you configure this property to be `true`, the SDK library would be contain * simulation mode. In the simulation mode, the SDK library would not communicate * with the real backend server, but just returns random mock-up data * with requestion data validation. * * For reference, random mock-up data would be generated by `typia.random<T>()` * function. * * @default false */ simulate?: boolean; /** * Target directory that e2e test functions would be placed in. * * If you configure this property and runs `npx nestia e2e` command, * `@nestia/sdk` will analyze your NestJS backend server code, and * generates e2e test functions for every API endpoints. * * If not configured, you can't run `npx nestia e2e` command. */ e2e?: string; /** * Whether to use propagation mode or not. * * If being configured, interaction functions of the SDK library would * perform the propagation mode. The propagation mode means that never * throwing exception even when status code is not 200 (or 201), but just * returning the {@link IPropagation} typed instance, which can specify its body * type through discriminated union determined by status code. * * @default false */ propagate?: boolean; /** * Whether to clone DTO structures or not. * * If being configured, all of DTOs used in the backend server would be cloned * into the `structures` directory, and the SDK library would be refer to the * cloned DTOs instead of the original. * * @default false */ clone?: boolean; /** * Whether to wrap DTO by primitive type. * * If you don't configure this property as `false`, all of DTOs in the * SDK library would be automatically wrapped by {@link Primitive} type. * * For refenrece, if a DTO type be capsuled by the {@link Primitive} type, * all of methods in the DTO type would be automatically erased. Also, if * the DTO has a `toJSON()` method, the DTO type would be automatically * converted to return type of the `toJSON()` method. * * @default true */ primitive?: boolean; /** * Whether to assert parameter types or not. * * If you configure this property to be `true`, all of the function * parameters of SDK library would be checked through * [`typia.assert<T>()` function](https://typia.io/docs/validators/assert/). * * This option would make your SDK library compilation time a little bit slower, * but would enahcne the type safety even in the runtime level. * * @default false */ assert?: boolean; /** * Whether to optimize JSON string conversion 10x faster or not. * * If you configure this property to be `true`, the SDK library would utilize the * [`typia.assertStringify<T>() function`](https://github.com/samchon/typia#enhanced-json) * to boost up JSON serialization speed and ensure type safety. * * This option would make your SDK library compilation time a little bit slower, * but would enhance JSON serialization speed 10x faster. Also, it can ensure type * safety even in the runtime level. * * @default false */ json?: boolean; } export declare namespace INestiaConfig { /** * List of files or directories to include or exclude to specifying the NestJS * controllers. */ interface IInput { /** * List of files or directories containing the NestJS controller classes. */ include: string[]; /** * List of files or directories to be excluded. */ exclude?: string[]; } /** * Building `swagger.json` is also possible. */ interface ISwaggerConfig { /** * Output path of the `swagger.json`. * * If you've configured only directory, the file name would be the `swagger.json`. * Otherwise you've configured the full path with file name and extension, the * `swagger.json` file would be renamed to it. */ output: string; /** * OpenAPI version. * * If you configure this property to be `2.0` or `3.0`, the newly generated * `swagger.json` file would follow the specified OpenAPI version. The newly * generated `swagger.json` file would be downgraded from the OpenAPI v3.1 * specification by {@link OpenApi.downgrade} method. * * @default 3.1 */ openapi?: "2.0" | "3.0" | "3.1"; /** * Whether to beautify JSON content or not. * * If you configure this property to be `true`, the `swagger.json` file would * be beautified with indentation (2 spaces) and line breaks. If you configure * numeric value instead, the indentation would be specified by the number. * * @default false */ beautify?: boolean | number; /** * Whether to include additional information or not. * * If configured to be `true`, those properties would be added into each * API endpoinnt. * * - `x-nestia-method` * - `x-nestia-namespace` * ` `x-nestia-jsDocTags` * * @default false */ additional?: boolean; /** * API information. * * If omitted, `package.json` content would be used instead. */ info?: Partial<OpenApi.IDocument.IInfo>; /** * List of server addresses. */ servers?: OpenApi.IServer[]; /** * Security schemes. * * When generating `swagger.json` file through `nestia`, if your controllers or * theirs methods have a security key which is not enrolled in here property, * it would be an error. */ security?: Record<string, OpenApi.ISecurityScheme>; /** * List of tag names with description. * * It is possible to omit this property or skip some tag name even if * the tag name is used in the API routes. In that case, the tag name * would be used without description. * * Of course, if you've written a comment like `@tag {name} {description}`, * you can entirely replace this property specification. */ tags?: OpenApi.IDocument.ITag[]; /** * Decompose query DTO. * * If you configure this property to be `true`, the query DTO would be decomposed * into individual query parameters per each property. Otherwise you set it to be * `false`, the query DTO would be one object type which contains all of query * parameters. * * @default true */ decompose?: boolean; /** * Operation ID generator. * * @param props Properties of the API endpoint. * @returns Operation ID. */ operationId?(props: { class: string; function: string; method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; path: string; }): string; } }