Swagger Codegen(Nest.js)

Summary

Automatic code generation tool that creates Nest.js framework projects based on Swagger Yaml file information

To create a yaml file

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]

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)

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

parameters:
  - $ref: "#/components/parameters/x-access-token"
  - in: query
    name: id
    required: true
    description: Board 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-codgen-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
  x-codegen-request-body-name: BoardCreateRequest
  content:
    application/json:
      schema:
        type: object
        $ref: "#/components/schemas/BoardCreate"

#Number Two
requestBody:
  description: Board Create DTO
  #Request DTO Class Name
  x-codegen-request-body-name: "UpdateBoardRequest"
  content:
    application/json:
      schema:
        type: object
        # x-codegen-request-body-name Class Properties
        properties:
          id:
            description: Board Key
            type: number
            example: 1
          name:
            description: Board Name
            type: string
            example: Ryan Board
          comment:
            description: Board Comment
            type: object
            $ref: "#/components/schemas/Comment"

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

    # x-codegen-request-body-name ResponseDTO Class Name
    x-codegen-request-body-name: "BoardListResponse"
    content:
      application/json:
        schema:
          type: object
          # x-codegen-request-body-name Class Properties
          properties:
            common:
              type: object
              $ref: "#/components/schemas/CommonResponse"
            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
      properties:
        code:
          description: Success Code
          type: integer
          example: 200
        success:
          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
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: Board Name
        eCommant:
          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
      properties:
        id:
          description: "Baord Key"
          example: 1
          type: number
        name:
          description: Board Name
          example: Board Name
          type: string
        eCommant:
          description: Comment Object
          type: array
          items:
            $ref: "#/components/schemas/Comment"

    Comment:
      type: object
      properties:
        id:
          type: number
          description: "Comment Key"
          example: 1
        content:
          type: string
          description: "Comment Content"
          example: Hellow

    BoardCreate:
      description: Board Create
      type: object
      properties:
        id:
          description: "Board Key"
          example: 1
          type: number
        name:
          description: Board Name
          example: Board Name
          type: string

        # In the properties attribute, a single object reference with a different data model reference method should be set to the object type
        oneCommant:
          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: MultiCommant
          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