Swagger API 사용법 1탄

 

"이번 프로젝트는 API를 만들어서 Swagger를 통해 공유하고,,, 어쩌고저쩌고,,"

Swagger,,, 갑자기 스웩이요?

 

 

 

제가 아는 그 스웩이요?

 

 

 

아니다.

정신 차리고 개념을 보자.

 

---

 

Swagger란?

 

"Swagger는 API 설명서를 자동으로 만들어 주는 도구이다."

쉽게 말하자면, API를 설명하고 시각화하며 테스트할 수 있게 도와주는 역할의 도구이다.

개발자와 클라이언트 간의 소통을 돕는 데 유용하다.

 

 

🤔 굳이 써야 하나요?

녜.

왜냐면

 

‼️ 개발자, QA, 클라이언트 간의 소통을 훨~~~씬 원활하게 해 줌

(알겠지만 프로젝트에서 가장 어려운 건 의. 사. 소. 통)

 

‼️ Swagger는 코드에서 바로 문서를 생성하므로 별도로 문서 작성할 필요 없음

(개발자는 귀찮은 문서작성 안 해서 좋고,

클라이언트는 복잡한 문서내용 쉽게 볼 수 있어서 좋고)

 

‼️ API가 여러 버전이 생길 수 있는데 이 또한 Swagger에서 자동으로 관리해 줌

(개발자 입장에서 너무 편함)

 

결론적으로, Swagger는 API 설명서의 Google Docs와 같은 역할을 한다.

쓰지 않을 이유가 없다.

 

---

 

각설하고, chatGPT를 활용한 데모 프로젝트를 만들어서 직접 익혀보자

 

 

 

1. VScode를 열고 터미널을 연다.(Ctrl + `)

 

 

2. 프로젝트 폴더를 만들 곳에, api_server라는 폴더명으로 폴더를 만든다.

 

 

 

3. File > open folder > api_server를 선택해서 연다.

 

 

4. 터미널에서 초기화하는 명령어를 입력한다.

( npm init -y에서 -y의 의미는 npm init을 진행하면서 많은 질문들에 다 yes로 진행하겠다는 의미이다.)

 

 

 

5. swagger-ui-express를 설치한다.

 

❓ swagger-jsdoc란 코드에 작성된 JSDoc 주석을 기반으로 Swagger 문서를 생성

❓  swagger-ui-express란 생성된 Swagger 문서를 UI형태로 보여줌

 

 

 

6. 그럼 이제 실제 서버를 만들어보자.

우선 index.js라는 파일을 생성해 준다.

 

 

 

그럼 api_server 폴더에 index.js 파일이 생성된 게 확인된다.

 

 

7. 이제 생성된  index.js 파일에 하단 내용을 붙여 넣기 한다.(chat GPT 참조)

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');

const app = express();
const port = 3000;

// Swagger 설정
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'A simple API documentation',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'], // API 경로
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);

// Swagger UI 엔드포인트
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// JSON 데이터 처리
app.use(express.json());

// 기본 라우트
app.get('/', (req, res) => {
  res.send('Hello, API Server!');
});

// API 라우트 추가
const apiRoutes = require('./routes/api');
app.use('/api', apiRoutes);

// 서버 시작
app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
  console.log(`Swagger docs available at http://localhost:${port}/api-docs`);
});

 

 

8. 그다음에 Swagger 문서에 추가될 API 경로는 별도의 파일로 분리하기 위해, routes라는 폴더를 생성하고 그 하위에 api.js파일을 생성한다.

 

 

 

9. 그럼 이제 api_server 폴더 하위에 routes라는 폴더가 생기고, 그 안에 api.js파일이 생성돼있는 게 확인 가능할 것이다.

 

10. 그럼 생성된 api.js 파일에 하단 내용을 붙여 넣기 한다.(chatGPT 참조)

const express = require('express');
const router = express.Router();

/**
 * @swagger
 * /api/hello:
 *   get:
 *     summary: Returns a hello message
 *     responses:
 *       200:
 *         description: A hello message
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                   example: "Hello, World!"
 */
router.get('/hello', (req, res) => {
  res.json({ message: 'Hello, World!' });
});

module.exports = router;

 

 

세팅은 이게 끝이다.

 

 

11. 그럼 이제 실행을 위해 터미널에 하단 명령어를 입력해서 실행시킨다.

 

 

 

12. localhost:3000을 실행해 보자.

 

 

짜잔

잘 나온다.

 

---

 

주소창에 localhost:3000/api-docs를 입력하면 아래와 같은 화면이 뜬다.

 

 

 

default에 있는 /api/hello 항목은 우리가 아까 세팅할 때 만든 데모 데이터이다.

버튼을 아래로 눌러보면

 

 

Curl과 URL로 요청할 수 있는 방법이 나와있고, 아래에 응답코드와 내용 그리고 응답헤더가 포함되어 있다.

Try it out 버튼을 눌러서 excute를 누르면 실행이 가능하다.

(현재 데모 데이터는 GET방식이라 parameter를 입력받는 형태가 아니라서 변경사항이 없다)

 

 

심화과정은 2탄으로..👍 

 

https://ashley-choi.tistory.com/61

Swagger API 사용법 2탄