WIL

6주차를 마무리하며... (Swagger)

흙으로만든형 2022. 8. 23. 11:53

6주차를 마무리하며.....

Clone주차에 접어 들어서야 겨우

기본기인 CRUD가 어느정도 잡힌것 같다. 하지만 아직 참고하며 만들어야 한다.

안보고 어느정도 맞을 정도가 되도록 연습해야겠다.

예외처리를 어떤 방식으로 해야 더 효과적일까?

폴더구조를 어떤 방식으로 나누어야 더 효율적일까?

고민하며 연습해봐야겠다.

실전 주차에 내가 무엇을 할 수 있을지 뭐가 안되고 뭐가 필요한지 급하게 생각하지 말고
천천히 해야할 일을 차례대로 적어 조금씩 앞으로 전진해보자!

Swagger

Open Api Specification(OAS)를 위한 프레임워크이다.
API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트/문서
API 사용 방법을 사용자에게 알려주는 문서
Springboot에서 Swagger를 사용하면, 컨트롤러에 명시된 어노테이션을 해석하여 API문서를 자동으로 만들어준다.
참고로 Swagger는 Java에 종속된 라이브러리가 아니다.
URL에 /swagger-ui.heml으로 접근하면 swagger가 만들어주는 페이지에 접근할 수 있다.
공식 사이트

Swagger의 기능

API Design (API 설계)
- Swagger-editor를 통해 api를 문서화하고 빠르게 명세 가능
API Development
- Swagger-codepen을 통해 작성된 문서를 통해 SDK를 생성하여 빌드 프로세스를 간소화할 수 있도록 도와준다.
API Documentation
- Swagger-UI를 통해 작성된 API를 시각화시켜준다.
API Testing
- Swagger-Inspector를 통해 API를 시각화하고 빠른 테스팅을 진행할 수 있다.
Standardize
- Swagger-hub를 통해 개인, 팀원들이 API 정보를 공유하는 Hub

app.js에

ㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡㅡ

🌈 Swagger

오늘은 swagger에 대해 알아봅시다!

swagger를 정의하기에 앞서, 필요성에 대해 이야기 해볼게요.

API 제작이 끝난 후에, 프론트 분에게 완성된 API를 전달합니다.

여러분들은 어떻게 전달해주시나요?

github Wiki 나, md 파일, 엑셀, notion 등 많은 방법이 있습니다.

하지만, 모두 공통점은 수기로 작성해야 한다는 점이죠.

API를 공유할 때 문제점은 없었나요 ?

수기로 작성할 때에는 꼼꼼한 확인이 필요하죠.

특히 API는 정해진 규칙을 따르기 때문에 오탈자 하나도 큰 영향을 줄 수 있어요.

혹은, API를 수정을 할 때에도 API 명세서를 수정하지 않으면 프런트 개발자가 심한....욕을....ㅎㅎ....

이러한 문제점을 해결할 수 있는 방법이 바로 Swagger입니다.

The OpenAPI Specification (OAS) defines
a standard, language-agnostic interface to RESTful APIs which allows both humans and computers
to discover and understand the capabilities of the service
without access to source code, documentation, or through network traffic inspection.
When properly defined, a consumer can understand and interact with the remote service
with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools
to display the API, code generation tools to generate servers and clients
in various programming languages, testing tools, and many other use cases.

- swagger.io

요약하자면, 사용자는 최소한의 구현 논리로 서비스를 이해하고 상호 작용할 수 있습니다.

그럼, swagger가 어떻게 생겼는지 먼저 확인해볼까요 ?

위와 같이 프로젝트 내에서 정의한 내용들을 보기좋은 UI로 제공합니다.

자, 이제 swagger에 대한 이해가 되었을까요❓

이제부터는 node 프로젝트에 적용시켜보겠습니다 〰️

⏳ Swagger Settings

크게 먼저 보면,

npm 모듈을 설치하고, 그 이후에 swagger에 대한 옵션등을 설정을 하겠습니다.

그리곤 path를 설정해 자신의 IP에서 확인할 수 있도록 설정합니다.

✔️ npm module 설치

자 먼저, npm 모듈을 설치할 거예요.

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

위와 같이 두 개의 모듈을 설치합니다.

swagger는 개발용 모듈이기 때문에 devDependencies에 추가해줘야겠죠❓

그래서 [--save-dev] 옵션을 붙여주었습니다.

✔️ Options

지금부터는 Basic Structure를 설정해볼게요.

공식 문서에 더 자세히 나와있습니다.

프로젝트 구조와 파일 형식은 다 다르겠지만, 저는 modules라는 폴더에 swagger.js 파일을 만들었습니다.

출처: https://gngsn.tistory.com/69 [pageseo:티스토리]

modules 폴더 swagger.js파일

모듈을 불러오고 옵션을 설정한 내용들 뿐입니다.

swaggerDefinition는 yaml 형식이나 json 형식을 받습니다.위는 json을 사용했죠 〰️

info 객체는 title, version, description 을 설정했습니다.

링크에 들어가시면 더 자세한 내용들을 확인할 수 있습니다 !

apis 는 내가 설정한 api들을 swagger가 찾을 수 있도록 표시해줍니다.

"/routes 파일 아래 js 파일 내에 정의 하고 있으며, /swagger 폴더 아래 swagger 설정을 정의하고 있다"를 명시해준거죠.

이제 설정을 했으니, 적용을 시켜보겠습니다.

✔️ app.js, 라우팅 설정

먼저, swagger.js 를 불러옵니다.

const { swaggerUi, specs } = require('./modules/swagger');

그리곤, /api-docs 라는 path로 등록시켜줍니다.

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

이 부분은 모든 path를 정의하기 전 (express에서는 indexRouter 윗 부분) 에 정의하는 게 좋겠죠?

여기까지 했다면, 설정은 끝났습니다 ❗️

여기까지 실행을 해보면 /api-docs 에 아래와 같이 뜨는 것을 확인할 수 있습니다 !

🤖 Swagger, 정의하기

자 이젠 생성한 api를 리스트에 등록해볼게요 !

✔️ API 등록

/**
 * @swagger
 *  /product:
 *    get:
 *      tags:
 *      - product
 *      description: 모든 제품 조회
 *      produces:
 *      - application/json
 *      parameters:
 *        - in: query
 *          name: category
 *          required: false
 *          schema:
 *            type: integer
 *            description: 카테고리
 *      responses:
 *       200:
 *        description: 제품 조회 성공
 */
router.get('/', getList);

swagger를 기존 js 파일에 적용하려면 @swagger을 반드시 붙여주셔야 합니다 !

그 아래에는 /product가 있는데요.

경로를 나타냅니다.

경로를 설정하는 데에는 몇 가지 방법을 확인할 수 있는데요.

📌 경로 설정

1. 아주 기본적으로 /path 만을 적을 수 있습니다.

2. 파라미터를 넣을 수 있습니다. /path/{path_parameter_name}

query는 아래 parameters에 정의를 해주어야 합니다.

parameters 아래에 in : path로 설정하면 됩니다

3. query를 추가할 수도 있습니다. /path/query=q1 이 형태는 어떻게 표시할까요?

parameters 아래 보면 in : query 를 확인할 수 있습니다 !

📌 메소드

그 아래에는 메소드를 get, post, put, delete 등등 을 설정합니다.

📌 그 밖의 통신 규칙과 설명들

그 아래에 다양한 설정들을 볼 수 있습니다.

tags 는 해당 API의 태그인데요. /api-docs 페이지에서 그 태그 별로 리스팅해줍니다.

description 는 해당 API를 설명하고

produces 는 content-type을 명시합니다.

parameters, requestBody, reposnses

등이 있습니다. 내부 정의 내용은 비슷하니 설명은 생략하겠습니다!

링크 걸어두었으니, 필요할 때마다 찾아보세요 !

✔️ 컴포넌트 정의

이번엔, 컴포넌트를 정의를 해보겠습니다.

# /swagger/product.yml

components:
  schemas:
    Product:
      properties:
        id:
          type: integer
          description: 제품 고유 번호
        title:
          type: string
          description: 제품 이름
        main_image:
          type: string
          description: 제품 메인 이미지
        discount:
          type: integer
          description: 할인 내역

참고로, yaml(yml)은 JSON과 XML과 같이 데이터 직렬화 양식이지만,

들여쓰기만을 이용하는 나열하는 아주아주 간단한 표기법입니다.

이젠 components를 정의해볼게요.

path 정의와는 다르게, components로 시작합니다.

이렇게 정의해두고 api의 결과 객체를 설명해줄 수 있습니다.

위의 파일을 적고 나서 가장 중요한건, api 설정에 추가해주어야 한다는 점입니다.

/**
 * @swagger
 *  /product:
 *    get:
 *      // ... 
 *      responses:
 *       200:
 *        description: 제품 조회 성공
          // 아래 schema 추가
 *        schema:
 *          $ref: '#/components/schemas/Product'
 */
 router.get('/', getList);

schema: $ref를 추가해줍니다.

보이시나요?

맨 아래 Example Value에 정의 했던 id, title, main_image, discount 가 출력되었습니다.

한 번 정의해두면 여러번 적지않아도 내용을 전달할 수 있겠죠 ?

위에는 Model을 누른 상태입니다.

위와 비슷하게 definitions이 있는데, 둘 다 model을 정의합니다.

출처: https://gngsn.tistory.com/69 [pageseo:티스토리]