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 - [email protected]
• Blog - https://any-ting.tistory.com/

A Company That Uses Open Source

Requirements

• Node.js v14.+

Install

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

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

CLI

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

CLI Examples

# 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_file> (Swagger Yaml file to reference)
  -p, --procjet_name <procjet_name> (Name of the project you want to create)

Example Project

# Example File Path example/example.yaml (Running a example file)
$ codegen-example

Support for automatic module creation

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

  2. Kafka

What to do after creating a project

 # Package install
 $ npm i & yarn install

 # Sort project code format
 $ npm run format

YAML Creation Rules

Common Rule

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

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

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

      operationId: healthCheck

Parameters Rule

Description

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

#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

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

#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

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

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