[Spring] (MAC, IntelliJ, vue.js) OpenAPI인 Swagger 적용하고 YAML 작성해보기.

 

 

Swgger를 사용하여
REST API를 작성해보고자 한다.
🐠

 

 

---

1. Swagger란?

2. Swagger 등록하기

3. Swagger 작성 방법

4. YAML으로 작성해 보기

5. 마무리

---

 

 

 

 

1. Swagger란?

 

Swagger는 REST API를 설명하고, 문서화하고, 테스트할 수 있게 해주는 도구이다. Swagger를 사용하면, 만든 API의 명세서를 자동으로 만들어주거나 쉽게 작성할 수 있도록 도와준다. 이때 Swagger는 OpenAPI Specification이라는 표준 명세서 포맷을 사용한다. (그래서일까, OpenAPI라고 부르는 듯하다.)

 

 

 

---

 

 

 

 

2. Swagger 등록하기.

 

□ build.gradle에 들어가기.

 

 

□ dependencies에 코드 등록하기.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

 

 

□ 코끼리 눌러서 다시 gradle 하기.

• 첫 번째 방법

 

• 두 번째 방법

 

 

□ 주소창 아래 중 하나를 입력한다.

• 주로 많이 사용하는 주소는 http://localhost:8080/swagger-ui/index.html 이다.

http://localhost:8080/swagger-ui.html
http://localhost:8080/swagger-ui/index.html
http://localhost:8080/swagger-ui/

 

 

□ 결과

 

 

 

---

 

 

 

 

3. Swagger 작성 방법

 

□ 컨트롤러나 DTO 코드에 주석(@Operation)으로 설명 추가하기.

• 코드와 명세가 자동으로 항상 일치한다.
• 코드만 바꿔도 명세가 실시간으로 갱신된다.
• 관리가 편하고, 팀 내 커뮤니케이션 비용이 낮다.

@Operation(summary = "회원가입", description = "신규 사용자를 등록합니다.")
@PostMapping("/api/join")
public UserResponse join(@RequestBody...) {
}

 

 

□ yaml/json 파일로 직접 명세를 작성한다.

• 백엔드와 프론트가 완전히 분리된 경우 사용한다.
• 문서만 공유하면 여러 언어, 팀에서 동시 활용 가능하다.
• 코드가 변경되면 따로 업데이트를 해줘야 한다.

openapi: 3.0.0
info:
  title: join-web
  version: 1.0.0
paths:
  /api/join:
    post:
      summary: 회원가입
      ...

 

 

□ 둘을 혼합하는 방식

• 초기 API 설계 단계에는 yaml 등으로 초안을 만든다.
• 개발 단계에서 코드로 주석을 더 상세히 다는 식으로 혼합해서 사용한다.

 

 

 

---

 

 

 

 

4. yaml으로 작성해 보기. 

 

주석으로 다는 것과 yaml으로 작성하는 것 모두 해볼 것이다. 실무에서 어떤 걸 더 선호할지 모르기도 하고, 한 번도 겪어본 적 없으니 둘 다 하면서 무엇이 더 편리하고 각 방법에 어떤 이점이 있는지 직접 느껴볼 것이다. 물론 처음 해보는 거라 후에 변경될 내용과 잘못된 내용이 있을 것이다. 

 

 

□ 회원가입 관련 코드

• 일단 회원가입만 하는 부분만 yaml으로 작성했다.
• 해당 파일을 만들기 전 docs 디렉터리를 만들었다.
• docs 디렉터리는 src와 같은 위치에 있고, docs에서 File을 열어 openapi.yaml이라고 작성했다.

openapi: 3.0.1
info:
  title: 회원가입 API
  version: 1.0.0
paths:
  /api/register:
    post:
      summary: 회원가입
      description: 이름, 아이디, 비밀번호, 전화번호, 생년월일, 이메일을 받는다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - userid
                - password
                - passwordConfirm
                - phone
                - birth
                - email
              properties:
                name:
                  type: string
                  description: 이름
                userid:
                  type: string
                  description: 아이디
                password:
                  type: string
                  format: password
                  description: 비밀번호
                passwordConfirm:
                  type: string
                  format: password
                  description: 비밀번호확인
                phone:
                  type: string
                  description: 전화번호
                birth:
                  type: string
                  format: date
                  description: 생년월일(변동가능성있음)
                email:
                  type: string
                  format: email
                  description: 이메일

      responses:
        '200':
          description: 가입 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: success
                  id:
                    type: integer
                    example: 1
                  message:
                    type: string
                    example: 회원가입이 완료되었습니다.

        '400':
          description: 가입 실패
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: fail
                  message:
                    type: string
                    example: 아이디가 중복입니다 or 비밀번호가 일치하지 않습니다.

 

 

 

□ 키워드 살펴보기. (참고로 설명이 완벽하진 않습니다)

• 명세서 작성 시 가장 기본적인 YAML 키워드이다.
• 여기에 적힌 키워드 중 필요한 키워드만 작성한다.

YAML 키워드	의미
paths	API 엔드포인트 경로를 적는다.
summary	해당 경로에서 무슨 일을 하는지 요약하여 적어둔다.
description	summary는 요약해서 적었으면 description은 어떤 내용인지 자세하게 적는다.
requestBody	request를 보낼 때 Body에 어떤 데이터가 들어가는지 정의한다. POST, PUT 등 Body가 필요한 경우 required: true라고 작성한다.
content	Body 데이터가 어떤 타입으로 오가는지 정한다. json이면 application/json으로 적고 form이면 application/x-www-form-urlencoded 또는 multipart/form-data로 적는다.
schema	Body의 실제 데이터 구조를 적는다. 예를 들면 회원가입의 경우 이름, email, 전화번호 등 이런 것들이 Body에 들어가게 된다.
properties	객체가 어떤 값을 가지고 있는지 적는다.
format	기본 타입보다 더 구체적인 데이터의 형식을 명시한다.
$ref	이미 정의해둔 데이터 구조를 참조해서 재사용한다.
example	값의 예시를 적는다.
reponses	응답을 보낸다.

 

 

• format은 type만으로 부족한 데이터의 구체적인 형식을 추가로 명시한다.

format	구체적인 형식
email	이메일 형식
date	날짜(YYYY-MM-DD)
date-time	날짜/시간(ISO 8601)
password	비밀번호
int64	64비트 정수

 

 

 

 

□ 코드를 부분적으로 살펴보기

• 요청

paths:
  /api/register:
    post:
      summary: 회원가입
      description: 이름, 아이디, 비밀번호, 전화번호, 생년월일, 이메일을 받는다.
      requestBody:
        required: true

paths에 /api/register라는 경로를 넣었다. post는 HTTP 메서드 방식으로 GET, POST, PUT 등 다양한 방식 중에 POST 방식을 선택했다. summary는 간략하게 어떤 기능을 하는지 적었고, description은 구체적인 설명을 적었다. 물론 이 부분은 패스해도 상관없다. GET 방식은 쿼리스트링(URL)에 내용을 넣어 보낸다. 그래서 보안에 좋지 않다. 회원가입은 보안이 필요하기 때문에 Body에 내용을 넣어 전달하는 POST 방식을 선택했다.(물론 POST 방식으로 전달했다고 보안이 완벽한 건 절대 아니다. 암호화가 필요하다) 그래서 requestBody에서 required 부분에 true라고 적었다. 정보를 찾아보면 required: true를 적지 않아도 딱히 문제는 없는 것 같다. (반드시 입력해야 한다고 알리는 정도의 역할만 하는 것 같다)

 

        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - userid
                - password

content에는 어떤 타입으로 오갈지 정하는 것으로 여기서는 json이라고 적었다. form 방식은 보통 텍스트와 파일 데이터가 함께 전송할 때 사용하는데, 회원가입은 텍스트 데이터만 오가면 되니까 json으로 지정했다. schema는 Body의 실제 데이터 구조를 적는다. 회원가입을 할 경우 Body에 올 데이터들은 이름, 아이디 비밀번호 등이 있다. required에 꼭 필요한 것들이 무엇인지 적었다. 그러면 type: object는 뭘까? 회원가입은 여러 값을 한 번에 주고받을 때 { "name": "sori", "userid":"sori123" }이런 식의 형태를 가진다. 중괄호로 묶여있고 여러 개의 키:값이 쌍으로 들어가서 object 형태가 된다.

 

              properties:
                name:
                  type: string
                  description: 이름
                userid:
                  type: string
                  description: 아이디
                password:
                  type: string
                  format: password
                  description: 비밀번호

properties는 객체가 어떤 값을 가지고 있는지 적는다. name과 userid, password는 string 타입이다. 그중 password는 format을 통해 구체적인 타입을 명시할 수 있다. OpenAPI(Swagger)에서 format: password로 하면 입력창이 비밀번호처럼 보인다. 사용자가 테스트할 때, 비밀번호가 노출되지 않도록 해준다.

 

• 응답

      responses:
        '200':
          description: 가입 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: success
                  id:
                    type: integer
                    example: 1
                  message:
                    type: string
                    example: 회원가입이 완료되었습니다.

responses는 응답으로 '200'이란 상태 코드를 적었다. content와 schema는 동일하게 적어주었다. 실제 body 내용에는 result와 id 그리고 message가 들어간다. result는 응답상태결과이며, id는 로그인할 때 쓰는 아이디가 아닌 데이터베이스에서 자동으로 부여하는 고유한 숫자이다. 회원가입이 성공이 됐는지 사용자에게 알리기 위한 message까지 넣었다. 회원가입이 완료되었습니다라는 문구는 사용자가 직접 보게 될 것이다.

 

 

        '400':
          description: 가입 실패
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: fail
                  message:
                    type: string
                    example: 아이디가 중복입니다 or 비밀번호가 일치하지 않습니다.

가입이 실패했을 때 '400'이란 응답코드를 보내며, result에 fail을 담아 서버에서 프론트로 보낼 것이다. 그리고 사용자에게 회원가입이 제대로 되지 않은 이유를 message에 담아 보낸다.

 

 

□ Swagger Editor 사용하기.

• 코드를 복붙하여 사용할 수 있다.

https://editor.swagger.io/

Swagger Editor

 

 

 

---

 

 

 

5. 마무리

 

YAML으로 OpenAPI(Swagger)를 작성해 봤다. 처음 작성해 보는 거라 맞는지도 잘 모르겠다. 아마 틀린 부분이나 빼먹은 부분이 많아서 추후에 수정을 하지 않을까 생각한다. 일단은 회원가입 하는 부분만 작성했는데, 간편 회원가입, 로그인 등 다른 파트는 나중에 해보도록 할 것이다. (너무 힘들었다...)

 

 

 

---

 

 

아래에 출처를 남겨두겠습니다.
블로그엔 제가 최대한 이해한 내용까지만 적는 거라
출처에 들어가시면 더 많은 내용이 있어 공부하시는데 도움 되실 겁니다.

 

🪽

틀린 내용이 있다면 댓글로 알려주세요

 

 

---

 

https://swagger.io/specification/v3/

-Swagger

OpenAPI Specification - Version 2.0 | Swagger

 

 

 

- Swagger 사용법

Swagger API 명세 만드는 법 1 - Swagger Hub에서 yaml 파일 생성

 

 

 

- YAML 작성방법

TIL > API 문서 작성하기 (swagger)

 

 

 

- JSON, FORM의 차이점

FormData와 JSON(body)의 차이점: 언제 어떤 방식을 사용해야 할까?

 

 

 

- YAML 작성 방법

Swagger API Yaml 기본 파일 작성

 

 

 

- Swagger 적용

[Swagger] 스프링 3.x Swagger 적용(With. SpringDocs)

 

 

 

- Swagger 사용

Swagger를 이용한 API 문서 자동화