Open API Document 도입에 대해

[Choi-JJunho]

서론

현재 문서화 방식에서 다음과 같은 문제를 인지했습니다.

• Notion, RestDocs 두가지의 문서가 존재하기 때문에 API 명세가 변경되면 둘 다 수정해줘야한다.
• API 명세가 변경된다면 RestDocs 적용을 위해 재배포 과정을 거처야한다.

최근 API First Design이라는 기법에 대해 찾아보던 도중 Open API Specification에 대해 알게 되었습니다.

OAS

RESTful API를 사전에 정의된 규칙에 맞게 API 스펙을 json이나 yaml로 표현하는 방식을 의미합니다.

https://swagger.io/specification/ 를 참고

yaml로 작성된 코드로 swagger 문서를 생성할 수 있습니다.

https://swagger.io/solutions/api-documentation/ 참고

더 나아가 해당 yaml 파일과 CodeGen을 이용한다면 실제 문서화를 위한 코드까지 작성할 수 있다는 특징이 있습니다.

https://openapi-generator.tech/ 참고

현재 명세되어있는 API를 yaml로 간단하게 작성해봤습니다.

해당 방식을 사용하면 단 하나의 명세서를 사용하여 API 변경에 따른 문서의 불일치 현상을 최소화 할 수 있다는 장점이 있습니다.
또한 yaml 언어 자체가 직관적이고 OAS와 관련한 문서화도 잘 되어있어 익숙해지는 데에도 큰 문제는 없다고 판단했습니다.

요약

두개 이상의 문서를 관리하면서 발생하는 불필요한 소요를 줄이고 싶었습니다.
이를 위해 OAS를 도입하여 하나의 문서로 API 스펙을 관리하는 방법을 생각해봤습니다.

여러분은 OAS 도입에 대해 어떻게 생각하시나요?

예시 코드

아래 코드를 https://editor-next.swagger.io/ 해당 사이트에 붙여넣기를 해서 생성되는 문서를 미리 확인해볼 수 있습니다.

openapi: 3.0.3
info:
  title: Pium API Document
  description: |-
    Pium Application API Document
  version: 1.0.0
servers:
  - url: https://api.piuml.life
tags:
  - name: dictionary-plants
    description: 사전 식물 관련 API
  - name: pet-plants
    description: 반려 식물 관련 API
  - name: member
    description: 사용자 관련 API
  - name: history
    description: 타임라인 관련 API
  - name: reminder
    description: 리마인더 관련 API
  - name: auth
    description: 인증 관련 API
paths:
  '/dictionary-plants/{id}':
    get:
      tags:
        - dictionary-plants
      summary: '반려식물 단건 조회'
      parameters:
        - name: id
          in: path
          description: 사전 식물 고유 ID
          required: true
          schema:
            type: integer
            format: integer64
      responses:
        '200':
          description: 요청 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DictionaryPetPlant'
        '404':
          description: 'Not Found'
  '/dictionary-plants':
    get:
      tags:
        - dictionary-plants
      summary: '반려식물 이름으로 조회'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DictionaryPetPlantsBySearch'
        '404':
          description: 'Not Found'

  '/pet-plants':
    get:
      tags:
        - pet-plants
      summary: 반려 식물 목록 조회
      security:
        - cookieAuth: [ ]
      responses:
        '200':
          description: 요청 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetPlants'
        '201':
          description: 요청 성공
          content:
            application/json:
              schema:
                properties:
                  hello:
                    type: string
                    example: dd
    post:
      tags:
        - pet-plants
      summary: 반려 식물 목록 조회
      requestBody:
        description: '반려 식물 생성 요청'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetPlantCreate'
      responses:
        '201':
          description: '요청 성공'
  '/pet-plants/{id}':
    get:
      tags:
        - pet-plants
      summary: 반려 식물 목록 조회
      security:
        - cookieAuth: [ ]
      parameters:
        - name: id
          in: path
          description: 사전 식물 고유 ID
          required: true
          schema:
            type: integer
            format: integer64
      responses:
        '200':
          description: 요청 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetPlant'
    patch:
      tags:
        - pet-plants
      summary: 반려 식물 단건 수정
      security:
        - cookieAuth: [ ]
      parameters:
        - name: id
          in: path
          description: 사전 식물 고유 ID
          required: true
          schema:
            type: integer
            format: integer64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePetPlant'
      responses:
        '200':
          description: 요청 성공

    delete:
      tags:
        - pet-plants
      summary: 반려 식물 단건 삭제
      security:
        - cookieAuth: [ ]
      parameters:
        - name: id
          in: path
          description: 반려 식물 고유 ID
          required: true
          schema:
            type: integer
            format: integer64
      responses:
        '204':
          description: 요청 성공

  '/reminders':
    get:
      tags:
        - reminder
      summary: '리마인더 조회'
      security:
        - cookieAuth: [ ]
      responses:
        '200':
          description: 요청 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reminder'
  '/reminders/{petPlantId}':
    post:
      tags:
        - reminder
      summary: '리마인더 조회'
      parameters:
        - name: petPlantId
          in: path
          description: 반려 식물 고유 ID
          required: true
          schema:
            type: integer
            format: integer64
      security:
        - cookieAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReminderWater'
      responses:
        '201':
          description: 요청 성공
    patch:
      tags:
        - reminder
      summary: '리마인더 조회'
      parameters:
        - name: petPlantId
          in: path
          description: 반려 식물 고유 ID
          required: true
          schema:
            type: integer
            format: integer64
      security:
        - cookieAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReminderChangeDate'
      responses:
        '200':
          description: 요청 성공

  '/history':
    get:
      tags:
        - history
      summary: '반려 식물 타임라인 조회'
      security:
        - cookieAuth: [ ]
      parameters:
        - name: petPlantId
          in: query
          description: 반려 식물 고유 번호
          required: true
          schema:
            type: integer
            format: integer64
        - name: page
          in: query
          description: '페이지 번호 (0부터 시작)'
          schema:
            type: integer
            format: integer64
        - name: size
          in: query
          description: 한 페이지 데이터 개수
          required: false
          schema:
            type: integer
            format: integer64
        - name: filter
          in: query
          description: 필터링 정보
          required: false
          schema:
            type: string
            example: 'lastWaterDate,waterCycle,flowerpot,wind,light,location'
      responses:
        '200':
          description: 요청 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetPlantHistory'

  '/members/me':
    get:
      tags:
        - member
      summary: '유효 세션 확인'
      security:
        - cookieAuth: [ ]
      responses:
        '200':
          description: 인증 성공
        '401':
          description: 인증 실패
  '/members/withdraw':
    post:
      tags:
        - member
      summary: '회원 탈퇴'
      security:
        - cookieAuth: [ ]
      responses:
        '204':
          description: 탈퇴 성공
  '/login':
    post:
      tags:
        - auth
      summary: '로그인'
      security:
        - cookieAuth: [ ]
      parameters:
        - name: code
          in: query
          description: 로그인 코드 정보
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 요청 성공
  '/logout':
    post:
      tags:
        - auth
      summary: '로그아웃'
      security:
        - cookieAuth: [ ]
      responses:
        '200':
          description: 요청 성공
components:
  schemas:
    DictionaryPetPlantsBySearch:
      title: 'DictionaryPetPlantsBySearch'
      description: '사전 식물 검색 결과'
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: 아카시아
              image:
                type: string
                example: 'https://image.com'
    DictionaryPetPlant:
      title: 'DictionaryPetPlant'
      description: '사전 식물 기본 정보'
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: 다육이
        image:
          type: string
          example: 'https://image.com'
        familyName:
          type: string
          example:
            example: '백합과'
        smell:
          type: string
          example: '거의 없음'
        poison:
          type: string
          example: '있음'
        manageLevel:
          type: string
          example: '초보자'
        growSpeed:
          type: string
          example: '보통'
        requireTemp:
          type: string
          example: '16~20도'
        minimumTemp:
          type: string
          example: '13도 이상'
        requireHumidity:
          type: string
        postingPlace:
          type: array
          items:
            type: string
          example: [ '실내 어두운 곳', '거실 내측', '거실 창측', '발코니 내측' ]
        waterCycle:
          type: object
          properties:
            spring:
              type: string
              example: '흙을 촉촉하게 유지 (물에 잠기지 않도록)'
            summer:
              type: string
              example: '흙을 촉촉하게 유지 (물에 잠기지 않도록)'
            autumn:
              type: string
              example: '흙을 촉촉하게 유지 (물에 잠기지 않도록)'
            winter:
              type: string
              example: '흙을 촉촉하게 유지 (물에 잠기지 않도록)'
    PetPlant:
      title: 'PetPlant'
      description: '반려 식물 정보'
      properties:
        id:
          type: integer
          example: 1
        nickname:
          type: string
          example: '나의 아카시아(별명)'
        imageUrl:
          type: string
          example: 'https://image.com'
        dictionaryPlant:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: '아카시아'
        location:
          type: string
          example: '거실'
        flowerpot:
          type: string
          example: '플라스틱'
        light:
          type: string
          example: '창 밖'
        wind:
          type: string
          example: '바람이 안통해요'
        birthDate:
          type: string
          example: '2000-01-08'
        lastWaterDate:
          type: string
          example: '2023-07-10'
        secondLastWaterDate:
          type: string
          example: '2023-07-10'
        waterCycle:
          type: integer
          example: 3
        dday:
          type: integer
          example: 10
        daySince:
          type: integer
          example: 2341
        nextWaterDate:
          type: string
          example: '2023-07-10'
    PetPlants:
      title: 'PetPlants'
      description: '반려 식물 목록 정보'
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 2
              nickname:
                type: string
                example: '기영이'
              imageUrl:
                type: string
                example: 'https://image.com'
              dictionaryPlantName:
                type: string
                example: '스투키'
              birthDate:
                type: string
                example: '2023-07-08'
              daySince:
                type: integer
                example: 95
    UpdatePetPlant:
      properties:
        nickname:
          type: string
          example: '기영이'
        flowerpot:
          type: string
          example: '플라스틱'
        waterCycle:
          type: integer
          example: 3
        light:
          type: string
          example: '창 밖'
        location:
          type: string
          example: '욕실'
        wind:
          type: string
          example: '바람이 안통해요'
        birthDate:
          type: string
          example: '2003-07-08'
        lastWaterDate:
          type: string
          example: '2023-07-10'
    PetPlantHistory:
      title: 'PetPlantHistory'
      description: '반려 식물 타임라인 단건 조회 결과'
      properties:
        page:
          type: integer
          example: 0
        size:
          type: integer
          example: 10
        elementSize:
          type: integer
          example: 235
        hasNext:
          type: boolean
          example: true
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: 'lastWaterDate'
              date:
                type: string
                example: '2023-07-01'
              content:
                type: object
                properties:
                  previous:
                    type: string
                    example: 'EMPTY'
                  current:
                    type: string
                    example: '2023-07-01'
    Reminder:
      title: 'Reminder'
      description: '리마인더 조회 정보'
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              petPlantId:
                type: integer
                example: 1
              image:
                type: string
                example: 'image.com'
              nickName:
                type: string
                example: '참새나무'
              dictionaryPlantName:
                type: string
                example: '알로카시아'
              dday:
                type: integer
                example: 3
              nextWaterDate:
                type: string
                example: '2023-07-07'
              lastWaterDate:
                type: string
                example: '2023-07-16'
    PetPlantCreate:
      title: 'PetPlantCreate'
      description: '반려식물 생성 정보'
      properties:
        dictionaryPlantId:
          type: integer
          example: 1
        nickname:
          type: string
          example: "기영이"
        location:
          type: string
          example: "거실"
        flowerpot:
          type: string
          example: "플라스틱"
        waterCycle:
          type: integer
          example: 7
        light:
          type: string
          example: "창 밖"
        wind:
          type: string
          example: "바람이 안통해요"
        birthDate:
          type: string
          example: "2023-07-08"
        lastWaterDate:
          type: string
          example: "2023-07-10"
    ReminderWater:
      properties:
        waterDate:
          type: string
          example: '2023-06-12'
    ReminderChangeDate:
      properties:
        nextWaterDate:
          type: string
          example: '2023-06-12'
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: JSESSIONID

[bassyu]

캬 너무 좋아요!!

1. 우선 API 문서를 하나로 통일하는 게 좋아 보여요!
2. 필요한 API 문서 정보는 데이터로서 관리하고, 어떻게 보여질지는 툴이 알아서 하니
   주노가 소개해 준 OAS를 선택하는 것도 상당히 매력적으로 느껴지네요!
3. 노션은 자유형식이었는데 템플릿을 주니, 'API 문서를 만들기 위해 필요한 정보들'을 안내받는 느낌이네요!

질문도 있습니다!
RestDocs는 OAS에 비해서 수정이 더 번거로운가요?

[Choi-JJunho]

질문에 대한 답변을 드리자면 RestDocs는 테스트 코드의 성공으로 작성되는 문서다보니 테스트코드와 같이 생각해야한다는 부분에서 RestDocs가 OAS에 비해서 수정이 더 번거롭다고 생각합니다 😅

[Kim0914]

개인적으로 swagger UI를 좋아해서 좋아보이네요 ㅎㅎ (docs는 문서의 성향이기 때문에 보여지는 부분이 상당히 중요하다고 생각 !)

몇 가지 궁금한 점이 있습니다 😀

첫 번째, 저는 yaml 파일을 읽어보니 스웨거를 애플리케이션 코드단에 작성하지 않고 yaml 파일에 그대로 옮겨놓은 것 같더라구요 !
그래서 두 개이상의 문서를 관리했을 때 발생하는 불필요한 소요를 어떻게 줄일 수 있는지 궁금합니다 ㅎㅎ

yaml 파일이기 때문에 프론트 백엔드 구분없이 작성할 수 있다는 장점은 존재하지만, 결국 swagger 설정을 yaml 파일로 그대로 작성하기 때문에(정확히는 잘 모르겠지만?)현재 진행하고 있는 노션에 작성 -> yaml 파일에 작성 과정을 동일하게 반복할 것 같다는 생각이 들어요 !!

두 번째, 이전에 어떤 docs를 사용할 지 토론을 진행했었습니다 ㅎㅎ

• API 문서화에 대한 이야기 #181

그 과정에서 rest docs를 사용하기로 했던 이유 중 하나가 테스트 코드를 기반으로 한 신뢰성있는 문서라는 점이었는데요 !
OAS도 신뢰성을 기반으로 한 문서를 제작할 수 있는지 궁금합니다 😎
만약 그렇지 않다면, 신뢰성있는 문서 or 두 개이상의 문서를 관리할 때 생기는 소요 중 어떤 점에 비중을 두는 것이 좋을지 다른 분들의 의견이 궁금하네요 !

마지막으로 Rest docs는 배포를 해야 변경된 부분을 확인할 수 있는데, OAS도 결국 yaml을 바탕으로 swagger config를 생성해주는 것 같은데 배포를 하지 않고 적용할 수 있나요?!?!!? (가능하다면 정말 멋있는 친구 💚)

[Choi-JJunho]

첫번째 질문에 대한 답변을 드리자면 yaml 파일 자체가 문서의 의미를 가진다고 생각하면 될 것 같습니다~!
이 부분에 대해서는 이에 API문서를 노션에 작성하지 않고 yaml 파일을 주된 문서로써 사용하게 될 것 같아요

두번째 관련해서는 아직 학습이 더 필요하지만 gradle 설정을 통해 API spec과 일치 여부를 확인하는 방법이 있다고 들었어요! (gradle 버전 호환성 문제가 있다고 듣기도 했습니다..)

[Choi-JJunho]

지금 다시 생각해봤을 때 다음과 같은 문제점이 인지되어 지금은 close 하겠습니다~

• 기존 문서화 과정을 개편하는 과정에서 생기는 불편함을 감수할만큼 결과물이 유의미하지 않다.
• Open API Document 도입 과정에서 팀 내에서 발생하는 학습비용에 대한 추산이 명확하지 않다. + 그만큼의 시간도 없다.