Swagger Codegen(Nest.js)

Automatic code generation tool for creating Nest.js framework projects based on Swagger Yaml file information based on Open API 3.0 version

Stay in touch

- Author - Ryan
- Email - ryansin937@gmail.com
- Blog - https://any-ting.tistory.com/

A Company That Uses Open Source

Requirements

- Node.js v14.+

Install

``bash


npm

$ npm install -g @newko/swagger-nestjs-codegen

yarn

$ yarn global add @newko/swagger-nestjs-codegen
`

CLI

`bash
$ codegen -s [swagger.yaml] -p [project name]
`




CLI Examples

`bash


1. How to create a project with a new name

$ codegen -s swagger.yaml -p swagger

2. To create a project based on your current location

$ codegen -s swagger.yaml -p .

#Options
options :
-s, --swagger_file (Swagger Yaml file to reference)
-p, --procjet_name (Name of the project you want to create)
`




Example Project

`bash


Example File Path example/example.yaml (Running a example file)


$ codegen-example
`

Support for automatic module creation

`bash
1. Databases
- MySQL : TypeORM, Sequelize
- MariaDB : TypeORM, Sequelize
- MongoDB : Mongose

2. Kafka
`




What to do after creating a project

`bash
# Package install
$ npm i & yarn install

# Sort project code format
$ npm run format
`




YAML Creation Rules

Common Rule

`text
1. If you don't write an explanation and an example, there will be no error, but please make sure to write it. (Used for comments)

2. When defining schema properties, make sure to write the type. (Typescript-based)

3. Please declare the array type as items.

4. Please use $ref for object type and array type. (That way, the YAML file will not be long.) Also, the code will be generated by referring to the correct data.

5. When you create an example, it is set to the default value.

6. Object types or array types are automatically mapped without creating an example (the class you reference itself is the default value)
`

Paths Rule




> Description

`text
1. Please write down the API routing path with a kebab case.

2. You must create a tag and OperationId in the HTTP method (which works with the domain and class methods)

3. Summary and description are used for annotations (not necessarily required)
`

> Examples

`yaml
paths:
/health-check:
get:
tags:
- HealthCheck
summary: Health check server....
description: Health check API for that server

operationId: healthCheck
`




Parameters Rule




> Description

`text
1. If you are referring directly to the $ref value, find and define the $ref reference model properties.

2. in, name, schema.Please be sure to fill in the type.

3. You can mix it up.
`

> Examples

`yaml
#Set client request parameters
#If you use the $ref reference method
parameters:
- $ref: "#/components/parameters/x-access-token"
- in: query
name: id
required: true
description: "board unique key"
schema:
type: number

- in: query
name: name
description: "board name"
schema:
type: string
`




RequestBody & Response Rule




> Description

`text
1. Make sure to fill out the x-codegen-request-body-name tag.
The class name is set (Ex: BoardCreateRequest)

2. If you refer to one $ref value immediately, apply the value of the referenced Model attribute

3. If you do not refer to the $ref value immediately, define the properties tag and create it.
(Content → Application/json → Schema → Properties)

4. Only the response 200 information applies to the codegen.

5.
`

> Examples

`yaml
#Number One
requestBody:
#Request DTO Class Name
#If $ref is referenced immediately, the BoardCreate schema property referenced to the BoardCreateRequest class name is applied.
x-codegen-request-body-name: "BoardCreateRequest"
content:
application/json:
schema:
type: object
$ref: "#/components/schemas/BoardCreate"


#Number Two
requestBody:
description: "create board dto"
#x-codegen-request-body-name Request DTO Class Name
x-codegen-request-body-name: "UpdateBoardRequest"
#If $ref is not referenced, the UpdateBoardRequest class is created based on the information declared in properties.
content:
application/json:
schema:
type: object
required:
- "id"
- "name"
- "comment"
properties:
id:
description: "borad unique key"
type: number
example: 1
name:
description: "board name"
type: string
example: "ryan test board name"
comment:
description: "board comment"
type: object
$ref: "#/components/schemas/Comment"

#Number three
responses:
"200":
description: "success info"

# x-codegen-request-body-name ResponseDTO Class Name
x-codegen-request-body-name: "BoardListResponse"
content:
application/json:
schema:
type: object
required:
- "data"
# x-codegen-request-body-name Class Properties
properties:
data:
type: "array"
items:
$ref: "#/components/schemas/Board"

`

Schemas Rule




> Description

`text
1. Use only schema and parameters within components to match the Nest.js framework structure with the Swagger Yaml file spec structure.

2. Write based on common rules.
`

> Example

`yaml
components:
schemas:
HealthCheck:
type: object
required:
- "code"
- "success"
properties:
code:
description: "success code"
type: number
example: 200
success:
description: "success type"
type: boolean
example: true

# In the properties attribute, a single object reference with a different data model reference method should be set to the object type
Board:
type: object
required:
- "id"
- "name"
- "eComment"
properties:
id:
description: "board unique key"
type: number
example: 1
name:
description: "board name"
type: string
example: "Board Name"
eComment:
description: "comment object"
type: object
$ref: "#/components/schemas/Comment"

# If it is an array type referring to another Data Model in properties properties
# Array type must be set to array and items must be declared
Board2:
type: object
required:
- "id"
- "name"
- "eComment"
properties:
id:
description: "board unique key"
type: number
example: 1
name:
description: "board name"
type: string
example: "Board Name"
eComment:
description: "comment object"
type: array
items:
$ref: "#/components/schemas/Comment"

Comment:
type: object
required:
- "id"
- "content"
properties:
id:
description: "board unique key"
type: number
example: 1
content:
description: "comment content"
type: string
example: "Hello, nice to meet you"

BoardCreate:
description: "create board"
type: object
required:
- "id"
- "name"
- "oneComment"
- "multiCommant"
properties:
id:
description: "board unique key"
type: number
example: 1
name:
description: "board name"
type: string
example: "Board Name"

# In the properties attribute, a single object reference with a different data model reference method should be set to the object type
oneComment:
description: "one comment"
type: object
$ref: "#/components/schemas/Comment"

# If it is an array type referring to another Data Model in properties properties
# Array type must be set to array and items must be declared
multiCommant:
description: "multi commant"
type: array
items:
$ref: "#/components/schemas/Comment"

#name If the value is not used as a variable name, use key as a variable name
parameters:
x-access-token:
in: header
name: "x-access-token"
schema:
type: string
description: Access-Token
required: true
``