OpenLab - Kotlin, 토이프로젝트에 대한 EventStorming 과 API 정의

KIDO 24.06.17

222 2 0

facebook twitter kakao link

2 0

facebook twitter kakao link

DEVOTEE 요약: Kotlin OpenLab에서는 이벤트 스토밍과 API 스펙 정의에 대해 학습하고 각자의 이벤트 스토밍 결과를 공유한 후, OpenAPI Spec을 사용하는 방법에 대해 다루었습니다. API 스펙 작성은 JSON/YAML 형식을 지원하며, 서버/클라이언트 코드 자동 생성을 위해 OpenAPI 3.0 버전을 기준으로 작성했습니다. 다음 과제로는 배운 내용을 토대로 API 정의서를 OpenAPI 스펙 형식으로 작성하는 것이 주어졌고, 향후 발표 예정입니다.

DEVOTEE 추천 블로그

지금까지 Kotlin OpenLab은 이벤트 스토밍, 그리고 개략적으로 우리가 무엇을 만들지에 대한 이야기를 했었습니다.

숙제로 각자 이벤트 스토밍을 해보고, 서로 공유하는 시간을 가졌습니다.

오늘은 다음 작업을 진행했습니다 .

1. 이벤트 스토밍 > API 스펙 정의

2. API 스펙을 OpenAPI Spec 공부하기

API Spec 정의하기

사용자 관련

Aggregate

사용자
- 사용자 아이디
- 사용자 이름
- 사용자 phone
- 사용자 메일주소
- 사용자 비밀번호
- 사용자 비밀번호 확인
- 사용여부
- 탈퇴여부
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
사용자 토큰
- accessToken
- refreshToken
사용자 조회 조건
- 사용자 정보: 사용자 Aggregate
- 일자 조건: 생성일/수정일
- 조회 시작일시: YYYYMMDDHHmmss
- 조회 종료일시: YYYYMMDDHHmmss
- Sort Field: 소트대상 필드
- Sort Option: ASC/DESC
사용자 목록:
- 사용자 Aggregate Lists
- PageInfo
  - page
  - size
- totalCount: 총 건수
- selectedCount: 조회된 건수

API 목록

사용자 가입
- Uri: /v1/users
- Method: POST
- Input Params: 사용자 Aggregate
- Results: 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 목록 조회
- Uri: /v1/users
- Method: GET
- Input Params: 사용자 조회 조건 Aggregate
- Results: 사용자 목록
- 성공: 200
- 실패: 400, error Message
사용자 상세 조회
- Uri: /v1/users/{userId}
- Method: GET
- Input Params: userId - PathVariable
- Results: 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 정보 수정
- Uri: /v1/users/{userId}
- Method: PUT
- Input Params:
  - userId: PathVariable
  - 사용자 Aggregate
- Results: 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 탈퇴
- Uri: /v1/users/{userId}
- Method: DELETE
- Input Params: userId - PathVariable
- Results: true/false
- 성공: 200
- 실패: 400, error Message
사용자 로그인
- Uri: /v1/auth/users
- Method: POST
- Input Params:
  - 사용자 Aggregate
- Results:
  - 사용자 토큰 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 인증
- Uri: /v1/auth/uses/verify
- Method: PUT
- Input Params:
  - 인증 단축 URL PostFix
- Results: true/false
- 성공: 200
- 실패: 400, error Message
사용자 재인증
- Uri: /v1/auth/uses/reverify
- Method: PUT
- Input Params:
  - 사용자 Aggregate
- Results: true/false
- 성공: 200
- 실패: 400, error Message

Porject 관련

Aggregate

프로젝트
- 프로젝트 아이디
- 프로젝트 이름
- 프로젝트 설명
- 사용여부
- 삭제여부
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
프로젝트 목록:
- 프로젝트 Aggregate Lists
- PageInfo
  - page
  - size
- totalCount: 총 건수
- selectedCount: 조회된 건수
프로젝트 조회조건
- 프로젝트 정보: 프로젝트 Aggregate
- 일자 조건: 생성일/수정일
- 조회 시작일시: YYYYMMDDHHmmss
- 조회 종료일시: YYYYMMDDHHmmss
- Sort Field: 소트대상 필드
- Sort Option: ASC/DESC
프로젝트 권한
- 프로젝트 ID
- 사용자 ID
- 권한:
  - ADMIN: 프로젝트에 대한 모든 권한 (수정/삭제/사용자추가/권한부여)
  - OPERATOR: 프로젝트에 대한 오퍼레이션 수행가능
  - READER: 프로젝트 정보 보기
- 사용여부
- 삭제여부
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
프로젝트 사용자
- 프로젝트 권한 Aggregtate 목록
프로젝트 사용자 양도
- from 프로젝트 사용자 Aggregate
- to 프로젝트 사용자 Aggregate
프로젝트 사용자 권한 목록 조회 조건
- 프로젝트 권한 Aggregate
- 일자 조건: 생성일/수정일
- 조회 시작일시: YYYYMMDDHHmmss
- 조회 종료일시: YYYYMMDDHHmmss
- Sort Field: 소트대상 필드
- Sort Option: ASC/DESC
Project Key 정보
- name: 프로젝트 키 이름
- access key: 엑세스키
- secret key: 시크릿키
- timeToLive: 초단위 시간

API 목록

프로젝트 생성
- Uri: /v1/projects
- Method: POST
- Input Params: 프로젝트 Aggregate
- Results: 프로젝트 Aggregate
- 성공: 200
- 실패: 400, error Message
프로젝트 목록 조회
- Uri: /v1/projects
- Method: GET
- Input Params: 프로젝트 조회 조건 Aggregate
- Results: 프로젝트 목록 Aggregate
- 성공: 200
- 실패: 400, error Message
프로젝트 상세 조회
- Uri: /v1/projects/{projectId}
- Method: GET
- Input Params: projectId - PathVariable
- Results: 프로젝트 Aggregate
- 성공: 200
- 실패: 400, error Message
프로젝트 수정
- Uri: /v1/projects/{projectId}
- Method: PUT
- Input Params:
  - projectId - PathVariable
  - 프로젝트 Aggregate
- Results: 프로젝트 Aggregate
- 성공: 200
- 실패: 400, error Message
프로젝트 삭제
- Uri: /v1/projects/{projectId}
- Method: DELETE
- Input Params:
  - projectId - PathVariable
- Results: true/false
- 성공: 200
- 실패: 400, error Message
사용자 등록
- Uri: /v1/projects/{projectId}/users
- Method: POST
- Input Params:
  - projectId - PathVariable
  - 프로젝트 사용자 Aggregate
- Results:
  - 프로젝트 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 권한부여
- Uri: /v1/projects/{projectId}/users
- Method: PUT
- Input Params:
  - projectId - PathVariable
  - 프로젝트 사용자 Aggregate
- Results:
  - 프로젝트 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 권한 목록
- Uri: /v1/projects/{projectId}/users
- Method: GET
- Input Params:
  - 프로젝트 사용자 권한 목록 조회 조건 Aggregate
- Results:
  - 프로젝트 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 권한 삭제
- Uri: /v1/projects/{projectId}/users
- Method: DELETE
- Input Params:
  - 프로젝트 사용자 Aggregate
- Results:
  - 프로젝트 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
사용자 권한 양도
- Uri: /v1/projects/{projectId}/users/auth
- Method: POST
- Input Params:
  - 프로젝트 사용자 양도 Aggregate
- Results:
  - 프로젝트 사용자 Aggregate
- 성공: 200
- 실패: 400, error Message
Access key 사용요청
- Uri: /v1/projects/{projectId}/keys
- Method: POST
- Input Params:
  - 프로젝트 키 정보 Aggregate
- Results:
  - 프로젝트 키 정보 Aggregate
- 성공: 200
- 실패: 400, error Message

API Spec 관련

Aggregate

S3 위치정보
- 버킷명
- 디렉토리
- 파일이름
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
GitHub 정보
- 리포지토리 이름
- 브렌치이름
- 디렉토리
- 파일이름
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
API스펙 파일
- 파일아이디
- 파일경로
- 파일이름
- 파일크기
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
API스펙
- 스펙이름
- 프로젝트 Aggregate
- 스펙버젼 태깅: 최신 스펙 버젼 태깅
- 안정화 버젼 태깅: 안정화된 스펙버젼
- 스펙저장소타입: ALL, HOST, S3, GITHUB
- API스펙 파일 Aggregate
- S3 위치정보 Aggregate
- GitHub 정보 Aggregate
- audit
  - 생성일
  - 생성자
  - 수정일
  - 수정자
API스펙 목록:
- API스펙 Aggregate Lists
- PageInfo
  - page
  - size
- totalCount: 총 건수
- selectedCount: 조회된 건수
API스펙 조회조건
- API스펙 정보: API스펙 Aggregate
- 일자 조건: 생성일/수정일
- 조회 시작일시: YYYYMMDDHHmmss
- 조회 종료일시: YYYYMMDDHHmmss
- Sort Field: 소트대상 필드
- Sort Option: ASC/DESC

API 목록

API스펙 생성
- Uri: /v1/apis
- Method: POST
- Input Params: API스펙 Aggregate
- Results: API스펙 Aggregate
- 성공: 200
- 실패: 400, error Message
API스펙 목록 조회
- Uri: /v1/apis
- Method: GET
- Input Params: API스펙 조회 조건 Aggregate
- Results: API스펙 목록 Aggregate
- 성공: 200
- 실패: 400, error Message
API스펙 상세 조회
- Uri: /v1/apis/{apiId}
- Method: GET
- Input Params: apiId - PathVariable
- Results: API스펙 Aggregate
- 성공: 200
- 실패: 400, error Message
API스펙 수정
- Uri: /v1/apis/{apiId}
- Method: PUT
- Input Params:
  - apiId - PathVariable
  - API스펙 Aggregate
- Results: API스펙 Aggregate
- 성공: 200
- 실패: 400, error Message
API스펙 삭제
- Uri: /v1/apis/{apiId}
- Method: DELETE
- Input Params:
  - apiId - PathVariable
- Results: true/false
- 성공: 200
- 실패: 400, error Message
API스펙 파일업로드
- Uri: /v1/apis/{apiId}/file
- Method: POST
- Input Params:
  - apiId - PathVariable
  - API스펙 파일 Aggregate
- Results: API스펙 Aggregate
- 성공: 200
- 실패: 400, error Message
API스펙 다운로드
- Uri: /v1/apis/{apiId}/file/download/{version}
- Method: GET
- Input Params:
  - apiId - PathVariable
  - version - 다운로드 받을 버젼
- Results: API스펙 File
- 성공: 200
- 실패: 400, error Message
API스펙 태깅
- Uri: /v1/apis/{apiId}/tags
- Method: PUT
- Input Params:
  - apiId - PathVariable
  - API스펙 Aggregate
- Results: API스펙 Aggregate
- 성공: 200
- 실패: 400, error Message

위와 같이 진행하고 나니 우리가 어떤 API가 필요한지 개략적으로 답이 나왔습니다~.

이제는 진짜 실전 OpenAPI Spec을 공부했습니다.

Open API Spec 정의 기초

관련:
- https://editor.swagger.io/
- https://editor-next.swagger.io/
Documents:
- https://swagger.io/docs/specification/about/

OpenAPI Spec file 작성하기

openapi 를 이용하여 Server/Client 코드를 자동생성하기 위해서 Spec 파일을 생성해야한다.
openapi spec 파일은 JSON/YAML 형태를 지원하고 있으며 여기서는 yaml 형식을 이용할 것이다.
openapi spec은 현재 버젼 3.x와 2.x 스펙이 있으며, 여기서는 3.0을 기준으로 작성할 것이다.
샘플 스펙을 확인하기 위해서는 다음을 참조하자. editor.swagger.io
구체적인 메뉴얼은 다음을 참조하자. OpenAPI Guide

기본 구조 이해하기

openapi spec 파일은 다음과 같은 기본 구조를 가진다.

# 기본 영역 
openapi: 3.0.0
servers:
  - url: 'http://petstore.swagger.io/v2'
info:
  ... 생략

# tags 영역
tags:
  - name: pet
    description: Everything about your Pets
  ... 생략

# paths 영역 (endpoint uri)

paths:
  /pet:
    post:
  ... 생략

# components 영역 (스키마 영역)
components:
  requestBodies:
  ... 생략
  schemas:
  ... 생략

위와 같이 기본영역, tags영역, paths영역, components 영역으로 구성된다.

Spec 기본정보 설정하기

openapi: 3.0.0
servers:
  - url: 'http://petstore.swagger.io/v2'
info:
  description: >-
    This is a sample server Petstore server. For this sample, you can use the api key
    `special-key` to test the authorization filters.
  version: 1.0.0
  title: OpenAPI Petstore
  license:
    name: Apache-2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'

openapi
- 버젼을 나타낸다. 우리 샘플은 3.0.0 버젼임을 알 수 있다.
servers
- openapi 로 api가 요청하는 대상 서버의 url 경로를 지정한다.
- 이는 로컬에서 어플리케이션을 8080으로 띄웠다면 http://localhost:8080/v2 처럼 사용하면 될 것이다.
info
- openapi 의 정보를 기술한다.
- desription
  - 현재 스펙 파일에 대한 설명을 보여준다.
- version
  - 스펙의 버젼을 확인할 수 있다. 사용자가 직접 작성하며, 버젼에 따라 버젼번호를 올려주면 될 것이다.
- license
  - 현재 스펙의 라이선스 정보를 나타낸다. 사용자의 니즈에 맞게 라이선스를 지정하면 될 것이다.

태그 설정하기

tags:
  - name: pet
    description: Everything about your Pets
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user

tags는 현재 작성하는 스팩에서 지정한 REST API들이 어떤 그룹에 속하는지 지정할 수 있도록 하고 있다.
위 예제는 pet, store, user 로 3개의 그룹으로 REST API를 그룹 짓는다는 의미이다.

Path 지정하기

paths 키워드를 이용하면 이제 우리가 제공할 api의 스펙의 uri를 작성할 수 있다.

paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: ''
  ...생략...

위와 같이 paths 하위에는 여러개의 uri 경로를 지정할 수 있다.
이 의미는 yaml의 배열 형식으로 - 를 이용하여 여러개의 리소스 경로를 지정할 수 있음을 나타낸다.

Path의 기본 구조

paths의 하위에는 여러개의 리소스 경로 uri를 지정할 수 있으며, 이 경로를 통해서 클라이언트의 요청을 받아 들이게 된다.

  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: true
          style: form
          explode: false
          deprecated: true
          schema:
            type: array
            items:
              type: string
              enum:
                - available
                - pending
                - sold
              default: available
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value
      security:
        - petstore_auth:
            - 'read:pets'

위 코드는 매우 길어보이지만 지정된 형식을 가지고 있다.

path 기본 속성 설정정보

기본 속성 정보는 uri path에 대한 설명을 나타낸다.

  /uri-path:
    get: 
      tags: 
      summary:
      description:
      operationId:

/uri-path:
- 모든 paths의 시작은 uri 경로로 시작한다. REST API 작성법을 미리 참조하면 좋을 것이다. 다음 을 참조하자.
get:
- 리소스 요청을 위한 HTTP Methods 를 나타낸다.
- get, post, put, delete 등과 같은 메소드를 나타내며 uri path가 동일하다면, 하나의 uri에 여러 메소드를 사용할 수 있다.
tags:
- 어떠한 태그 그룹으로 현재 uri의 메소드가 속할지를 지정한다.
summary:
- 요약정보를 기술한다.
description:
- 상세 설명정보를 기술한다
operationId:
- 실제로 서버 스켈레톤을 생성할떼 사용될 함수 이름이 된다.
- openapi generator를 통해서 코드를 gen 하면 요청을 처리하는 핸들러 메소드이름이다.

파라미터 속성

uri에 대해서 요청이 들어온경우 어떠한 파라미터값이 전달되는지를 설정한다.

      parameters: 
        - name: myNmae
          in: query 
          description: 테스트 
          required: true
          schema: 
            type: array
            items: 
              type: 
              enum:

parameters:
- 파리미터 영역, 입력값으로 어떤값을 사용할지 지정 하게 된다.
- 파라미터 속성들을 나열사기 위해서는 배열 형태로 나열된다.
name:
- 파라미터의 이름을 지정한다.
in: query
- 파라미터가 어떠한 형식으로 작성되어야 하는지 지정한다.
- (query: uri 쿼리스트링 형태, path: pathVariable)
description:
- 파라미터 값을 설명한다.
required:
- 필수 여부 true이면 필수값, false이면 선택값
schema:
- 파라미터가 가질수 있는 데이터 타입을 지정한다.
type: array
- 스키마 타입을 지정한다. array는 배열을 의미한다.
- 타입값은 다음과 같은 값들이 올 수 있다.
  - array: 배열 혹은 리스트 형태의 파라미터
  - string: 문자열 형식의 파라미터
  - integer: 숫자 형식의 파라미터
  - boolean: 불리언타입의 파라미터
items:
- 배열형식 (array) 타입에 대해서는 items을 이용하여 배열의 데이터 타입을 구체적으로 지정할 수 있다.
format: int64
- 타입이 지정되었으면 타입에 해당하는 구체적인 포맷 형식을 지정한다.
- integer 타입에는 int64와 같이 데이터 형식이 들어간다.
- 날짜 타입이라면 string 타입을 지정하고, format으로 date-time로 지정한다.
enum:
- 나열형 값이라면 enum 을 지정하여 해당 값들만 올 수 있도록 규칙을 정한다.

응답 속성

응답 속성은 uri 요청에 대한 결과 형식을 기술한다.
보통 응답은 객체 형태로 결과가 반환된다.

      responses:
        '200':
          description:
          content:
            application/json:
              schema: 
                $ref: 
      security: <-- 보안속성을 설정한다.

responses:
- 응답 값임을 타나낸다.
'200':
- http status 코드를 지정한다. 200은 정상응답을 설정한다.
- 기타 다양한 http status를 지정하여, 특정 상황에 대한 응답 값을 지정할 수 있다.
description:
- 응답값의 내용을 기술한다.
content:
- 응답값의 내용이 시작됨을 나타낸다.
application/json:
- 응답 컨텐트의 타입을 지정한다. http스펙 중 content-type에 해당한다.
- json 타입으로 응답을 내보내고자 한다면 application/json 으로 지정한다.
schema:
- 응답 컨텐츠의 스키마를 지정한다.
$ref:
- 스펙 내부에 응답값의 스키마를 지정했다면 해당 스키마의 참조를 나타낸다.
- '#/components/schemas/Pet' 라고 한다면 스팩 내부에 components > schemas > Pet 라고 정의된 스키마 타입을 참조하라는 의미가 된다.
security:
- 보안속성을 설정한다.

RequestBody 구성하기

일반적으로 get 방식인 경우 queryString이나, pathVariable 형식으로 파라미터를 서버로 요청하게 된다.
그러나 post, put 등의 메소드는 복잡한 구조체의 형식으로 서버에 요청을 하게 된다.
이때 전달할 수 있는 방법이 RequestBody 형식이다.
아래는 post 형식으로 요청을 한 경우이다.

  paths:
  /pet:
    ... 생략
    put:
      ... 생략
      requestBody:
        $ref: '#/components/requestBodies/Pet'

requestBody:
- 요청시 json 타입으로 요청 바디에 요청 내용을 전달하는 경우이다.
$ref:
- 요청 내용을 지정한 스키마 혹은 요청 바디의 내용을 참조한다는 의미이다.
- '#/components/requestBodies/Pet' 은 components > requestBodies > Pet 에 정의한 스키마를 참조한다는 의미이다.
그리고 아래와 같이 requestBody를 작성한다.

components:
  requestBodies:
    Pet:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'
      description: Pet object that needs to be added to the store
      required: true

components:
- 요청 바디는 components 영역에 속한다는 것을 알 수 있다.
requestBodies:
- 요청 바디의 경우 components 하위에 requestBodies 영역에 기술된다.
Pet:
- 요청시 전달되는 데이터 객체의 이름이다. Pet라는 이름의 객체로 구성된다.
content:
- Pet 객체가 가진 내용을 기술한다.
application/json:
- 요청되는 데이터의 포맷을 나타낸다. 여기서는 json 타입으로 전달된다는 것을 알 수 있다.
schema:
- 요청 바디의 스키마가 어디에 정의 되어 있는지 나타낸다.
$ref:
- 요청 바디를 참조할 수 있는 경로를 기술한다.
- '#/components/schemas/Pet' 는 전달되는 컨텐츠가 components 하위에 schemas 영역내부에 Pet라는 객체를 참조한다는 것을 알 수 있다.
description:
- 요청 바디의 설명
required:
- 필수여부, true인경우 해당 요청시 컨텐츠가 없다면 오류가 난다

Schema 영역

Schema 영역은 입력/출력에 대한 객체를 나열하는 부분이다.
이 부분에 기술된 내용들은 코드가 생성될때 특정 개발 언어의 객체로 변환된다.

components:
  schemas:
    Pet:
      title: a Pet
      description: A pet for sale in the pet store
      type: object
      required:
        - name
        - photoUrls
      properties:
        id:
          type: integer
          format: int64
        category:
          $ref: '#/components/schemas/Category'
        name:
          type: string
          example: doggie
        photoUrls:
          type: array
          xml:
            name: photoUrl
            wrapped: true
          items:
            type: string
        tags:
          type: array
          xml:
            name: tag
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: pet status in the store
          deprecated: true
          enum:
            - available
            - pending
            - sold
      xml:
        name: Pet

components:
- shemas 역시 compolnents 하위 영역에 속한다.
schemas:
- 스키마를 나열하는 영역임을 알 수 있다.
Pet:
- 나열될 스키마의 이름이다.
- 코드가 생성이 되면 이 부분은 객체로 변환된다.
title:
- 스키마의 제목을 나타낸다.
description:
- 스키마의 설명을 나타낸다.
type: object
- 스키마 자체의 타입을 나타낸다. object는 객체를 의미한다.
required:
- 해당 스키마 내부의 속성중 필수 값을 나열한다.
- 필수 영역에 나열된 속성값은 notnull 이 된다.
properties:
- 스키마 내부에 포함될 프로퍼티(속성) 부분을 보여준다.
id:
- 스키마 하위에 속성 이름이다.
type:
- 속성의 타입을 지정한다.
- integer, string, array (items와 같이 사용됨), boolean 등이 온다.

WrapUp

우리는 지금까지 Open API Spec 에 대해서 설명하고, 이 API 스펙을 정의하면 어떠한 결과가 나오는지에 대해서 공부를 하게 되었습니다 .
다음번 숙제는 위 API 정의서를 OpenAPI 스펙으로 작성해 오는 것이었습니다.
두구두구, 다음번 발표는 다빈님이 발표해 주시기로 했습니다. (기대 됩니다 ^^)

#학습 모임 기록