OpenAPI Spec file 작성하기

• OpenAPI 를 이용하여 Server/Client 코드를 자동생성하기 위해서 Spec 파일을 생성해야한다.

• OpenAPI Spec 파일은 JSON/YAML 형태를 지원하고 있으며 여기서는 yaml 형식을 이용할 것이다.

• OpenAPI Spec은 현재 버젼 3.x와 2.x 스펙이 있으며, 여기서는 3.0을 기준으로 작성할 것이다.

• 샘플 스펙을 확인하기 위해서는 다음을 참조하자. editor.swagger.io

• Petstore 간단버젼: https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

• 구체적인 메뉴얼은 다음을 참조하자. 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

• 지금까지 간단하게, 스펙의 구조를 알아 보았다.

• 스펙은 크게, 스펙 기본정보, 태그정보(tags), 패스정보(paths), components(사용되는 요청 및 응답 스키마) 정보 등이 있다.