Swagger 사용해 보기

Swagger란

Swagger는 APi 개발 Workflow 전반에 걸쳐 일관성과 규율을 주도하도록 팀을 위해 구축된 통합 API 설계 문서 플랫폼입니다. 다시 말하자면, 구현할(구현한) API 명세와 API 테스트 수행을 동시에 가능하도록 도와주는 프레임워크입니다. 노션(Notion) 앱에 명세를 정리하고, Insomnia, Postman과 같은 툴로 테스트를 하는 과정을 한번에 할 수 있습니다.

개발된 API 설명서를 사용자에게 제공하면서 API를 테스트할 수 있는 Testbed를 제공할 수 있습니다다. 기존의 Open API들을 사용할 때, Postman을 이용해서 API 테스트를 하셨다면 이젠 Swagger를 사용하여 Open API 문서 작성하면서 테스트를 해 보세요.

 

더 빠르고 표준화된 API 설계

• 스마트 오류 피드백 및 구문 자동 완성 기능을 갖춘 강력한 편집기
• 코드 없이 작업을 가상화하는 API Mocking
• 여러 API에서 디자인 일관성을 보장하기 위한 스타일 유효성 검사기
• 여러 API에서 공통 OAS 구문을 저장, 재사용 및 참조하기 위한 도메인

안전한 API 협업

• API에 대한 효과적인 협업을 위한 조직 및 팀 관리
• 협업자와 소통하고 미해결 문제를 추적하기 위한 실시간 댓글
• 협업 워크플로에 대한 엄격한 제어를 위한 분기, 비교 및 병합
• Source Control 및 API  Gateway와 같은 API 수명 주기 솔루션과의 원활한 통합

API 수명 주기 촉진

• 클라우드에서 호스팅되는 중앙 내부 저장소에서 전체 API 수명 주기 조정
• API 정의 호스팅 및 액세스를 위한 중앙 저장소
• 지속적인 유지 관리 및 지속적인 반복을 위한 API 버전 관리
• 업데이트 및 API 변경을 추적하기 위한 자동 알림
• 손쉬운 배포를 위한 안전한 통합

호스팅된 대화형 API 문서

• Swagger UI 문서 자동 생성
• 문서화 프로세스를 계속하기 위해 OAS 정의 가져오기 및 호스트
• 기본 제공 권한 및 사용자 역할로 API 문서에 대한 액세스 관리
• 여러 API 문서 버전을 유지 관리하고 업데이트하기 위한 버전관리

간략하게 정의하자면, REST API 문서화를 도와주고 API를 바로 실행해서 테스트를 가능하게 하는 협업 도구이다.

 

Swagger 사용을 위해 express용 모듈 설치하기

아래 명령어를 이용해서 Swagger 사용에 필요한 모듈을 설치해준다.

$ npm i swagger-jsdoc swagger-ui-express --save-dev

• swagger-ui-express : API 문서 UI 렌더링을 위한 패키지
• swagger-jsdoc: Swagger 태그 주석을 추가해 API 문서화를 위한 패키지

 

Swagger 설정 파일 만들기

특정 폴더(예: ./src)에 Swagger.js 파일을 생성하여 아래와 같이 설정 내용을 작성합니다.

const options = {
  swaggerDefinition: {
    openapi: '3.1.0',
    info: {
      title: 'Express Service with Swagger!',
      version: '1.0.0',
      description: 'A REST API using swagger',
    },
    servers: [
      {
        url: 'http://localhost:8080',
      },
    ],
  },
  apis: ['/routes/*.js', './swagger/*', './models/*.js'],
};

export default options;

옵션 설명:

• openapi : 사용하는 Open API의 버전입니다. 현재 최신 버전은 3.1.0 입니다. (https://www.openapis.org/)
• info: (Optional) API에 필요한 정보
  • title: API 제목
  • version: API 버전
  • description: API 상세정보
• servers: API에 대한 기본 URL을 정의하며, 배열로 여러 URL 정의 가능 (host, basePath 이용하는 방법도 있음)
• components: (Optional) 모든 API에 사용할 공통 컴포넌트
• schemes: (Optional) 가능한 통신 방식 ex) ["http"], ["https"], ["http", "https"]
• defomotopms: (Optional) DB 모델 정의
• apis: files containing annotations as above

 

Swagger 서버 설정

익스프레스 실행 앱(예: app.js, main.js) Swagger 페이지로 사용할 UI를 생성해 줍니다.

import swaggerUi from 'swagger-ui-express';
import swaggerJsDoc from 'swagger-jsdoc';
import swaggerOptions from './src/swagger.js'; // 위치는 작업 환경에 맞추세요.
...
const specs = swaggerJsDoc(swaggerOptions);
app.use(
  '/api-docs',
  swaggerUi.serve,
  swaggerUi.setup(specs, { explorer: true })
);
...

이제 웹 브라우저에서 "localhost:8080/api-docs" URL을 입력합니다. 그러면 아래와 같은 Swagger 화면이 표시됩니다.

 

참고사이트

• [Swagger] RESTful API 문서 만들기 feat. YAML