<aside> ✏️

목차

</aside>

스웨거 문서 관련 수정

샘플용 코드 작성 이후, 스웨거에서 테스트해보고자 autogen 명령어 이후 서버를 열어보았는데,

이렇게 스웨거 문서에 post 관련 영역에 대해 request body, response body가 명시되어있지 않았습니다.

만들어진 swagger-output.json 문서를 보니 위와 같이 requset와 response에 대한 별도의 처리가 이루어지지 않았습니다.

// apps/server/controllers/exampleController.ts

export const createTodoController = async (req: Request, res: Response): Promise<void> => {
  /* 
    #swagger.summary = '새로운 Todo 생성'
    #swagger.description = '새로운 todo 항목을 생성합니다.'
    #swagger.tags = ['Todos']
    #swagger.requestBody = {
      required: true,
      content: {
        "application/json": {
          schema: {
            $ref: "#/components/schemas/Todo"  // 스키마 정보를 가져와 할당해줍니다.
          }
        }
      }
    }
    #swagger.responses[201] = {
      description: 'Todo 생성 성공',
      content: {
        "application/json": {
          schema: {
            $ref: "#/components/schemas/Todo"
          }
        }
      }
    }
    #swagger.responses[500] = {
      description: '서버 에러'
    }
  */
  try {
    const todo = await createTodo(req.body);
    res.status(201).json(todo);
  } catch (error: any) {
    res.status(500).json({ message: error.message });
  }
};

→ express도 마찬가지로 controller 함수 내부에서 주석으로 스웨거 문서에 올라갈 정보에 대해 적어놔야한다고 해서 적어줬습니다.

// apps/server/docs/swagger.ts

const options = {
  ...
    components: {
      schemas: {
        Todo: {
          type: 'object',
          properties: {
            todoid: { type: 'integer', example: 1 },
            content: { type: 'string', example: 'Sample todo content' },
            completed: { type: 'string', example: 'false' },
            created: { type: 'string', format: 'date-time', example: '2024-11-07T00:00:00.000Z' },
          },
          required: ['todoid', 'content'],
        },
      },
    },
  ...
}

→ 그리고 express의 swagger는 불친절하게도.. 스키마에 대한 정보도 자동으로 지정해주지 않아, options 객체 내부에 스키마 정보를 수동으로 작성해주어야합니다.

→ 만들어진 swagger-output.json 파일에서도 주석처리 해준 것처럼 정보가 변경된 것을 확인할 수 있습니다.

주석처리와 스키마 설정까지 잘 해주었고, 만들어진 스웨거 json 파일에서도 주석에 대한 변경사항이 잘 들어간 것을 확인했으나 막상 서버를 돌리면 아래와 같이 해당 components 경로를 찾을 수 없다. 라는 에러가 발생했습니다.

gpt한테 options 설정이나, 주석처리에 문제가 있는지 물어보았으니, gpt는 계속 swagger-jsdoc / swagger-autogen + swagger-ui-express 패키지를 분리하여 말하였고, 해결방안 또한 두가지 방식으로 분리하여 말했습니다.

의아해서 왜 둘을 분리한 방안밖에 없냐, 하였더니 swagger-jsdoc는 openapi 3.0.0 버전이고, swagger-autogen은 swagger 2.0.0 버전을 제공하기 때문이라고 하였습니다.