[API 명세 포멧을 이용한 API 디자인]

API 명세 포멧을 이용한 API 디자인

• OAS: 프로그래밍 언어에 상관없이 사용하는 REST API 명세
• Swagger 와 OAS 는 같은 개념이라고 보면 될듯
• YAML 을 JSON 으로 변환할 때 주석은 유실될 수 있음

OAS and JSON Schema

• 쿼리 파라미터의 묘사
  • 배열이나 리스트에 속하는 개발 원소는 - 로 표현

parameters:
-   name: free-query
	description: |
	in: query
	required: false
	# 데이터 구조 설명
	schema:
		type: string

JSON Schema 를 통한 데이터 묘사

• schema 에서 type 을 object 라고 명시할경우에는 properties 로 프로퍼티를 명시해줘야함
• type, properties, required required 아래에 배열형태로 명시된 property name 들은 필수값으로 지정이 됨
  • 각 속성의 type, description, example 추가로 명시가능
• 2-depth 이상으로 이루어질 경우 ex)

type: object
required:
  - reference
  - supplier
properties:
 reference:
   type: string
   description: 참고
   example: "안뇽ㅇ"
 supplier:
   type: object
   properties:
      ...

Describe Response

• status_code, description, content 순으로 명시하면됨
• content 는 가장 위에 미디어 타입도 같이 명시해줘야함

responses:
  "200":
    description: 랄랄라
    content:
      application/json:
        schema:
          ...

Describe Body Parameter

• description, media_type, schema

requestBody:
  description: 랄랄라
  content:
    application/json:
      schema:
        [...]

OAS 에서 API 를 효율적으로 묘사하기

• 컴포넌트 재사용하기: $ref 로 가능

schema:
  $ref: "#/schemas/common/...."

• Path Parameter 묘사하기
  • /products/{productId} 형식으로 명시 가능
  • in: path 로 명시
• 재사용 가능한 컴포넌트 묘사하기