nodejs / typescript / express API 문서 자동화 도입기 (실패)

현재의 문제

: type이 수정되면 swagger 주석도 수정해야한다

 

 

 

목표
: 담당 개발자가 아닌 사람들이 쉽게 API의 스펙을 확인할 수 있어야한다
: 정의한 type을 통해 API 문서를 만들고 싶다

 

 

 

사용중인 라이브러리

- swagger-jsdoc

: jsdoc 형태의 주석을 통해 스웨거 UI를 생성

 

- swagger-ui-express

: express 서버에 스웨거 API를 추가

 

 

고민하던 라이브러리
- swagger-autogen
: 쉽게 swagger 문서를 만들 수 있지만 swagger를 위한 스펙 작성이 필요함
: type이 변경되면 해당 문서에 대한 수정이 필요

: https://www.npmjs.com/package/swagger-autogen

- swagger-typescript-api
: swagger를 정의하고 type을 생성할 수 있다
: 현재 구조에서는 model단의 로직에서 사용하는 type이 변경되면 swagger yml을 수정해야한다

: https://www.npmjs.com/package/swagger-typescript-api

- @airtasker/spot
: 인터페이스를 통해 API 문서를 작성할 수 있는 것으로 보이나, 문서가 부족하며 API를 보기 위해 코드단까지의 접근이 필요함

: https://www.npmjs.com/package/@airtasker/spot?activeTab=readme

- tsoa
: typesecript의 주석을 이용하여 API의 메타데이터를 생성하는 라이브러리
: 데코레이터를 사용하며, (데코레이터를 지원하는 ES5 이상으로 바꿔야함) 클래스 구조의 컨트롤러에 대해서만 사용가능
: https://www.npmjs.com/package/tsoa
: https://tsoa-community.github.io/docs/getting-started.html

 

 

중간 결론
: type을 API 문서에 사용할 수는 없다. swagger yml과 type을 분리해서 관리해야한다
: 일단 swaggerUi를 이용하여 API단에 주석으로 swagger 문서를 작성하고,
  각 API의 스키마는 스키마 파일을 따로 둬서 관리하기로 했다
: 손으로 스키마를 현재 모델단에서의 타입과 동일하게 정의한뒤 라이브러리를 만들어서 커밋 시에 자동으로 type에 맞게
  스키마가 작성되게 만들어보고자 한다

 

최종 결론
: 현재의 컨트롤러 구조에서는 API 문서를 자동화할 수 없다
: 라우터 및 컨트롤러 구조를 클래스를 사용하는 방식으로 바꿔서 tsoa를 도입해야한다
: 현재 형상을 유지하려면 수동으로 해주는 수 밖에 없다 (내가 원하는 방식대로 지원하는 라이브러리가 없다)

 

※ 현재의 컨트롤러 구조

const express = require('express')
const app = express()
const database = require('./database')

app.get('/users', async (req, res) => {
  try {
    const users = await database.getUsers()
    res.json(users)
  } catch (error) {
    res.status(500).send('Internal Server Error')
  }
})

app.listen(3000, () => {
  console.log('Server is listening on port 3000')
})