์ ์ธ๊ณ์ ์ผ๋ก API๋ฅผ ์ค๊ณ, ๋ฌธ์ํ, ์ฌ์ฉํ๊ธฐ ์ํ OpenAPI ์ฌ์(OAS)์ ๋ํ ์ข ํฉ ๊ฐ์ด๋์ ๋๋ค. ๋ชจ๋ฒ ์ฌ๋ก์ ์ค์ฉ์ ์ธ ์์ ๋ฅผ ์์๋ณด์ธ์.
API ๋ฌธ์ํ: OpenAPI ์ฌ์ ์๋ฒฝ ๊ฐ์ด๋
์ค๋๋ ๊ณผ ๊ฐ์ด ๋ชจ๋ ๊ฒ์ด ์ฐ๊ฒฐ๋ ์ธ์์์ API(Application Programming Interface)๋ ํ๋ ์ํํธ์จ์ด ๊ฐ๋ฐ์ ๊ทผ๊ฐ์ ๋๋ค. API๋ ์๋ก ๋ค๋ฅธ ์์คํ ๊ฐ์ ์ํํ ํต์ ๊ณผ ๋ฐ์ดํฐ ๊ตํ์ ๊ฐ๋ฅํ๊ฒ ํ๋ฉฐ, ๋ชจ๋ฐ์ผ ์ ํ๋ฆฌ์ผ์ด์ ๋ถํฐ ๋ณต์กํ ์ํฐํ๋ผ์ด์ฆ ์๋ฃจ์ ์ ์ด๋ฅด๊ธฐ๊น์ง ๋ชจ๋ ๊ฒ์ ๊ตฌ๋ํฉ๋๋ค. ํจ๊ณผ์ ์ธ API ๋ฌธ์๋ ๊ฐ๋ฐ์๊ฐ API๋ฅผ ํจ์จ์ ์ผ๋ก ์ดํดํ๊ณ , ํตํฉํ๊ณ , ํ์ฉํ๋ ๋ฐ ๋งค์ฐ ์ค์ํฉ๋๋ค. ๋ฐ๋ก ์ด ์ง์ ์์ OpenAPI ์ฌ์(OAS)์ด ๋ฑ์ฅํฉ๋๋ค. ์ด ๊ฐ์ด๋๋ OAS์ ๋ํ ํฌ๊ด์ ์ธ ๊ฐ์, ๊ทธ ์ด์ , ๊ทธ๋ฆฌ๊ณ API ์ค๊ณ ๋ฐ ๋ฌธ์ํ๋ฅผ ์ํด OAS๋ฅผ ํจ๊ณผ์ ์ผ๋ก ํ์ฉํ๋ ๋ฐฉ๋ฒ์ ์ ๊ณตํฉ๋๋ค.
OpenAPI ์ฌ์(OAS)์ด๋ ๋ฌด์์ธ๊ฐ?
OpenAPI ์ฌ์(์ด์ ์๋ ์ค์จ๊ฑฐ ์ฌ์(Swagger Specification)์ผ๋ก ์๋ ค์ง)์ REST API๋ฅผ ์ํ ํ์ค์ ์ด๊ณ ์ธ์ด์ ๊ตฌ์ ๋ฐ์ง ์๋ ์ธํฐํ์ด์ค ๋ช ์ธ์ ๋๋ค. ์ด๋ฅผ ํตํด ์ฌ๋๊ณผ ์ปดํจํฐ ๋ชจ๋ ์์ค ์ฝ๋๋ ๋ฌธ์์ ์ ๊ทผํ๊ฑฐ๋ ๋คํธ์ํฌ ํธ๋ํฝ์ ๊ฒ์ฌํ์ง ์๊ณ ๋ ์๋น์ค์ ๊ธฐ๋ฅ์ ๋ฐ๊ฒฌํ๊ณ ์ดํดํ ์ ์์ต๋๋ค. OpenAPI๋ฅผ ํตํด ์ ๋๋ก ์ ์๋๋ฉด, ์๋น์๋ ์ต์ํ์ ๊ตฌํ ๋ก์ง๋ง์ผ๋ก ์๊ฒฉ ์๋น์ค๋ฅผ ์ดํดํ๊ณ ์ํธ์์ฉํ ์ ์์ต๋๋ค.
๊ธฐ๋ณธ์ ์ผ๋ก OAS๋ API์ ์๋ํฌ์ธํธ, ์์ฒญ ๋งค๊ฐ๋ณ์, ์๋ต ํ์, ์ธ์ฆ ๋ฐฉ๋ฒ ๋ฐ ๊ธฐํ ํ์ ์ธ๋ถ ์ ๋ณด๋ฅผ ๊ธฐ๊ณ๊ฐ ์ฝ์ ์ ์๋ ํ์(์ผ๋ฐ์ ์ผ๋ก YAML ๋๋ JSON)์ผ๋ก ์ค๋ช ํ๋ ๊ตฌ์กฐํ๋ ๋ฐฉ๋ฒ์ ์ ๊ณตํฉ๋๋ค. ์ด ํ์คํ๋ ํ์์ ๋ค์๊ณผ ๊ฐ์ ์๋ํ๋ ๋๊ตฌ ํ์ฉ์ ๊ฐ๋ฅํ๊ฒ ํฉ๋๋ค:
- ๋ฌธ์ ์์ฑ: ์ํธ์์ฉ์ ์ด๊ณ ์๊ฐ์ ์ผ๋ก ๋งค๋ ฅ์ ์ธ API ๋ฌธ์๋ฅผ ๋ง๋ญ๋๋ค.
- ์ฝ๋ ์์ฑ: ๋ค์ํ ํ๋ก๊ทธ๋๋ฐ ์ธ์ด๋ก ํด๋ผ์ด์ธํธ SDK์ ์๋ฒ ์คํ ์ ์๋์ผ๋ก ์์ฑํฉ๋๋ค.
- API ํ ์คํธ: API ์ ์๋ฅผ ๊ธฐ๋ฐ์ผ๋ก ์๋ํ๋ ํ ์คํธ๋ฅผ ๊ฐ๋ฐํฉ๋๋ค.
- API ๋ชจ์(mocking): ํ ์คํธ ๋ฐ ๊ฐ๋ฐ ๋ชฉ์ ์ผ๋ก API ๋์์ ์๋ฎฌ๋ ์ด์ ํฉ๋๋ค.
OpenAPI ์ฌ์ ์ฌ์ฉ์ ์ด์
OpenAPI ์ฌ์์ ์ฑํํ๋ฉด API ์ ๊ณต์ ์ฒด์ ์๋น์ ๋ชจ๋์๊ฒ ์๋ง์ ์ด์ ์ ์ ๊ณตํฉ๋๋ค:
ํฅ์๋ ๊ฐ๋ฐ์ ๊ฒฝํ
๋ช ํํ๊ณ ํฌ๊ด์ ์ธ API ๋ฌธ์๋ ๊ฐ๋ฐ์๊ฐ API๋ฅผ ๋ ์ฝ๊ฒ ์ดํดํ๊ณ ์ฌ์ฉํ ์ ์๋๋ก ํฉ๋๋ค. ์ด๋ ๋ ๋น ๋ฅธ ํตํฉ ์๊ฐ, ์ง์ ์์ฒญ ๊ฐ์, ์ฑํ๋ฅ ์ฆ๊ฐ๋ก ์ด์ด์ง๋๋ค. ์๋ฅผ ๋ค์ด, ๋์ฟ์ ๊ฐ๋ฐ์๊ฐ ๋ฐ๋์ ๊ธฐ๋ฐ์ ๋ ๊ฒฐ์ ๊ฒ์ดํธ์จ์ด์ ํตํฉํ๋ ค๋ ๊ฒฝ์ฐ, ๊ด๋ฒ์ํ ์ํต ์์ด๋ OpenAPI ์ ์๋ฅผ ์ฐธ์กฐํ์ฌ ํ์ํ ๋งค๊ฐ๋ณ์์ ์ธ์ฆ ๋ฐฉ๋ฒ์ ์ ์ํ๊ฒ ์ดํดํ ์ ์์ต๋๋ค.
ํฅ์๋ API ๊ฒ์ ๊ฐ๋ฅ์ฑ
OAS๋ฅผ ์ฌ์ฉํ๋ฉด API ์ ์๋ฅผ ๊ฒ์ ๊ฐ๋ฅํ ํ์์ผ๋ก ๊ฒ์ํ ์ ์์ผ๋ฏ๋ก ์ ์ฌ์ ์ฌ์ฉ์๊ฐ API์ ๊ธฐ๋ฅ์ ๋ ์ฝ๊ฒ ์ฐพ๊ณ ์ดํดํ ์ ์์ต๋๋ค. ์ด๋ ์กฐ์ง ๋ด์์ ์๋ง์ API๋ฅผ ์ฌ์ฉํ ์ ์๋ ๋ง์ดํฌ๋ก์๋น์ค ์ํคํ ์ฒ์์ ํนํ ์ค์ํฉ๋๋ค. OpenAPI ์ ์๋ก ๊ตฌ๋๋๋ ์ค์ ์ง์ค์ API ์นดํ๋ก๊ทธ๊ฐ ํ์๊ฐ ๋ฉ๋๋ค.
๊ฐ์ํ๋ API ๊ฑฐ๋ฒ๋์ค ๋ฐ ํ์คํ
API ์ค๋ช ์ ๋ํ ํ์ค ํ์์ ์ฑํํจ์ผ๋ก์จ API ์ํ๊ณ ์ ๋ฐ์ ๊ฑธ์ณ ์ผ๊ด์ฑ๊ณผ ํ์ง์ ๊ฐ์ ํ ์ ์์ต๋๋ค. ์ด๋ API ๊ฑฐ๋ฒ๋์ค๋ฅผ ๋จ์ํํ๊ณ API ์ค๊ณ ๋ฐ ๊ฐ๋ฐ์ ์ํ ๋ชจ๋ฒ ์ฌ๋ก๋ฅผ ์๋ฆฝํ ์ ์๊ฒ ํฉ๋๋ค. ๋ฐฉ๋ํ API ํ๊ฒฝ์ ๊ฐ์ง ๊ตฌ๊ธ์ด๋ ์๋ง์กด๊ณผ ๊ฐ์ ํ์ฌ๋ ๋ด๋ถ ํ์คํ๋ฅผ ์ํด API ์ฌ์์ ํฌ๊ฒ ์์กดํฉ๋๋ค.
์๋ํ๋ API ์๋ช ์ฃผ๊ธฐ ๊ด๋ฆฌ
OAS๋ ์ค๊ณ ๋ฐ ๊ฐ๋ฐ์์ ํ ์คํธ ๋ฐ ๋ฐฐํฌ์ ์ด๋ฅด๊ธฐ๊น์ง API ์๋ช ์ฃผ๊ธฐ ์ ๋ฐ์ ๊ฑธ์ณ ์๋ํ๋ฅผ ๊ฐ๋ฅํ๊ฒ ํฉ๋๋ค. ์ด๋ ์๋ ์์ ์ ์ค์ด๊ณ ํจ์จ์ฑ์ ๊ฐ์ ํ๋ฉฐ API๋ฅผ ๋ ๋น ๋ฅด๊ฒ ๋ฐ๋ณตํ ์ ์๊ฒ ํฉ๋๋ค. API ์ ์ ๋ณ๊ฒฝ์ด ์๋์ผ๋ก ๋ฌธ์ ์ ๋ฐ์ดํธ ๋ฐ ํ ์คํธ๋ฅผ ํธ๋ฆฌ๊ฑฐํ๋ ์ง์์ ํตํฉ/์ง์์ ๋ฐฐํฌ(CI/CD) ํ์ดํ๋ผ์ธ์ ์๊ฐํด๋ณด์ญ์์ค.
๊ฐ๋ฐ ๋น์ฉ ์ ๊ฐ
๋ฌธ์ ์์ฑ ๋ฐ ์ฝ๋ ์์ฑ๊ณผ ๊ฐ์ ์์ ์ ์๋ํํจ์ผ๋ก์จ OAS๋ ๊ฐ๋ฐ ๋น์ฉ๊ณผ ์์ฅ ์ถ์ ์๊ฐ์ ํฌ๊ฒ ์ค์ผ ์ ์์ต๋๋ค. ์ ํํ OpenAPI ์ ์๋ฅผ ๋ง๋๋ ๋ฐ ๋๋ ์ด๊ธฐ ํฌ์๋ ์ค๋ฅ ๊ฐ์์ ๊ฐ๋ฐ ์ฃผ๊ธฐ ๋จ์ถ์ ํตํด ์ฅ๊ธฐ์ ์ผ๋ก ๋ณด์๋ฐ๊ฒ ๋ฉ๋๋ค.
OpenAPI ์ ์์ ์ฃผ์ ๊ตฌ์ฑ ์์
OpenAPI ์ ์๋ API์ ๋ค์ํ ์ธก๋ฉด์ ์ค๋ช ํ๋ ๊ตฌ์กฐํ๋ ๋ฌธ์์ ๋๋ค. ์ฃผ์ ๊ตฌ์ฑ ์์๋ ๋ค์๊ณผ ๊ฐ์ต๋๋ค:
- OpenAPI ๋ฒ์ : ์ฌ์ฉ ์ค์ธ OpenAPI ์ฌ์์ ๋ฒ์ ์ ๋ช ์ํฉ๋๋ค(์: 3.0.0, 3.1.0).
- ์ ๋ณด(Info): ์ ๋ชฉ, ์ค๋ช , ๋ฒ์ , ์ฐ๋ฝ์ฒ ์ ๋ณด ๋ฑ API์ ๋ํ ๋ฉํ๋ฐ์ดํฐ๋ฅผ ์ ๊ณตํฉ๋๋ค.
- ์๋ฒ(Servers): API์ ๊ธฐ๋ณธ URL์ ์ ์ํฉ๋๋ค. ์ด๋ฅผ ํตํด ๋ค์ํ ํ๊ฒฝ(์: ๊ฐ๋ฐ, ์คํ ์ด์ง, ํ๋ก๋์ )์ ์ง์ ํ ์ ์์ต๋๋ค. ์๋ฅผ ๋ค์ด, `https://dev.example.com`, `https://staging.example.com`, `https://api.example.com`์ ๋ํด ์ ์๋ ์๋ฒ๊ฐ ์์ ์ ์์ต๋๋ค.
- ๊ฒฝ๋ก(Paths): ๊ฐ๋ณ API ์๋ํฌ์ธํธ(๊ฒฝ๋ก)์ ํด๋น ์์ (HTTP ๋ฉ์๋)์ ์ค๋ช ํฉ๋๋ค.
- ์ปดํฌ๋ํธ(Components): ์คํค๋ง, ์๋ต, ๋งค๊ฐ๋ณ์, ๋ณด์ ์คํค๋ง์ ๊ฐ์ ์ฌ์ฌ์ฉ ๊ฐ๋ฅํ ๊ฐ์ฒด๋ฅผ ํฌํจํฉ๋๋ค. ์ด๋ API ์ ์์ ์ผ๊ด์ฑ์ ๋์ด๊ณ ์ค๋ณต์ ์ค์ ๋๋ค.
- ๋ณด์(Security): API ์์ฒญ์ ์ธ์ฆํ๊ณ ๊ถํ์ ๋ถ์ฌํ๋ ๋ฐ ์ฌ์ฉ๋๋ ๋ณด์ ์คํค๋ง๋ฅผ ์ ์ํฉ๋๋ค(์: API ํค, OAuth 2.0, HTTP ๊ธฐ๋ณธ ์ธ์ฆ).
๊ฒฝ๋ก(Paths)์ ์์ (Operations) ์ฌ์ธต ๋ถ์
๊ฒฝ๋ก(Paths) ์น์ ์ OpenAPI ์ ์์ ํต์ฌ์ ๋๋ค. API์ ๊ฐ ์๋ํฌ์ธํธ์ ํด๋น ์๋ํฌ์ธํธ์์ ์ํํ ์ ์๋ ์์ ์ ์ ์ํฉ๋๋ค. ๊ฐ ๊ฒฝ๋ก์ ๋ํด HTTP ๋ฉ์๋(์: GET, POST, PUT, DELETE)์ ์์ฒญ ๋ฐ ์๋ต์ ๋ํ ์์ธํ ์ ๋ณด๋ฅผ ์ง์ ํฉ๋๋ค.
์ฌ์ฉ์ ํ๋กํ์ ๊ฒ์ํ๊ธฐ ์ํ API ์๋ํฌ์ธํธ์ ๊ฐ๋จํ ์๋ฅผ ์ดํด๋ณด๊ฒ ์ต๋๋ค:
/users/{userId}:
get:
summary: ID๋ก ์ฌ์ฉ์ ํ๋กํ ๊ฐ์ ธ์ค๊ธฐ
parameters:
- name: userId
in: path
required: true
description: ์กฐํํ ์ฌ์ฉ์์ ID
schema:
type: integer
responses:
'200':
description: ์ฑ๊ณต์ ์ธ ์์
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: ์ฌ์ฉ์ ID
name:
type: string
description: ์ฌ์ฉ์ ์ด๋ฆ
email:
type: string
description: ์ฌ์ฉ์ ์ด๋ฉ์ผ
'404':
description: ์ฌ์ฉ์๋ฅผ ์ฐพ์ ์ ์์
์ด ์์์:
/users/{userId}๋ ๊ฒฝ๋ก์ด๋ฉฐ, ์ฌ๊ธฐ์{userId}๋ ๊ฒฝ๋ก ๋งค๊ฐ๋ณ์์ ๋๋ค.get์ HTTP GET ๋ฉ์๋๋ฅผ ์ง์ ํฉ๋๋ค.summary๋ ์์ ์ ๋ํ ๊ฐ๋ตํ ์ค๋ช ์ ์ ๊ณตํฉ๋๋ค.parameters๋ ์ ๋ ฅ ๋งค๊ฐ๋ณ์๋ฅผ ์ ์ํ๋ฉฐ, ์ด ๊ฒฝ์ฐuserId๊ฒฝ๋ก ๋งค๊ฐ๋ณ์์ ๋๋ค.responses๋ HTTP ์ํ ์ฝ๋์ ์๋ต ์ฝํ ์ธ ์คํค๋ง๋ฅผ ํฌํจํ์ฌ ๊ฐ๋ฅํ ์๋ต์ ์ ์ํฉ๋๋ค.
์ฌ์ฌ์ฉ์ฑ์ ์ํ ์ปดํฌ๋ํธ(Components) ํ์ฉ
์ปดํฌ๋ํธ(Components) ์น์ ์ API ์ ์์์ ์ฌ์ฌ์ฉ์ฑ๊ณผ ์ผ๊ด์ฑ์ ์ฆ์งํ๋ ๋ฐ ์ค์ํฉ๋๋ค. ์ด๋ฅผ ํตํด ์คํค๋ง, ๋งค๊ฐ๋ณ์, ์๋ต๊ณผ ๊ฐ์ ์ฌ์ฌ์ฉ ๊ฐ๋ฅํ ๊ฐ์ฒด๋ฅผ ์ ์ํ๊ณ API ์ ์ ์ ์ฒด์์ ์ฐธ์กฐํ ์ ์์ต๋๋ค.
์๋ฅผ ๋ค์ด, ์ฌ์ฉ์ ํ๋กํ์ ๋ํ ์ฌ์ฌ์ฉ ๊ฐ๋ฅํ ์คํค๋ง๋ฅผ ์ ์ํ ์ ์์ต๋๋ค:
components:
schemas:
UserProfile:
type: object
properties:
id:
type: integer
description: ์ฌ์ฉ์ ID
name:
type: string
description: ์ฌ์ฉ์ ์ด๋ฆ
email:
type: string
description: ์ฌ์ฉ์ ์ด๋ฉ์ผ
๊ทธ๋ฐ ๋ค์ ์ฌ๋ฌ API ์๋ํฌ์ธํธ์ ์๋ต์์ ์ด ์คํค๋ง๋ฅผ ์ฐธ์กฐํ ์ ์์ต๋๋ค:
/users/{userId}:
get:
summary: ID๋ก ์ฌ์ฉ์ ํ๋กํ ๊ฐ์ ธ์ค๊ธฐ
parameters:
- name: userId
in: path
required: true
description: ์กฐํํ ์ฌ์ฉ์์ ID
schema:
type: integer
responses:
'200':
description: ์ฑ๊ณต์ ์ธ ์์
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
์ปดํฌ๋ํธ๋ฅผ ์ฌ์ฉํ๋ฉด ์ ์๋ฅผ ๋ณต์ ํ๋ ๊ฒ์ ํผํ๊ณ API ์ ์๋ฅผ ์ผ๊ด์ฑ ์๊ณ ์ ์ง๋ณด์ํ๊ธฐ ์ฝ๊ฒ ๋ง๋ค ์ ์์ต๋๋ค.
OpenAPI ์ฌ์ ์์ ์ ์ํ ๋๊ตฌ
OpenAPI ์ ์๋ฅผ ์์ฑ, ๊ฒ์ฆ ๋ฐ ํ์ฉํ๋ ๋ฐ ๋์์ด ๋๋ ์ฌ๋ฌ ๋๊ตฌ๊ฐ ์์ต๋๋ค:
- Swagger Editor: YAML ๋๋ JSON ํ์์ผ๋ก OpenAPI ์ ์๋ฅผ ์์ฑํ๊ณ ํธ์งํ๊ธฐ ์ํ ์น ๊ธฐ๋ฐ ํธ์ง๊ธฐ์ ๋๋ค. ์ค์๊ฐ ๊ฒ์ฆ ๋ฐ ์ ์ ๊ธฐ๋ฅ์ ์ ๊ณตํฉ๋๋ค.
- Swagger UI: OpenAPI ์ ์๋ฅผ ๋ํํ API ๋ฌธ์๋ก ๋ ๋๋งํ๋ ๋๊ตฌ์ ๋๋ค. ์ฌ์ฉ์๊ฐ API ์๋ํฌ์ธํธ๋ฅผ ํ์ํ๊ณ , ์์ฒญ์ ์๋ํ๊ณ , ์๋ต์ ๋ณผ ์ ์์ต๋๋ค.
- Swagger Codegen: OpenAPI ์ ์์์ ๋ค์ํ ํ๋ก๊ทธ๋๋ฐ ์ธ์ด๋ก ํด๋ผ์ด์ธํธ SDK ๋ฐ ์๋ฒ ์คํ ์ ์์ฑํ๋ ๋๊ตฌ์ ๋๋ค.
- Stoplight Studio: ์๊ฐ์ ์ธํฐํ์ด์ค์ ๊ณ ๊ธ ๊ธฐ๋ฅ์ผ๋ก API๋ฅผ ์ค๊ณํ๊ณ ๋ฌธ์ํํ๊ธฐ ์ํ ๋ฐ์คํฌํฑ ์ ํ๋ฆฌ์ผ์ด์ ์ ๋๋ค.
- Postman: OpenAPI ์ ์ ๊ฐ์ ธ์ค๊ธฐ ๋ฐ ๋ด๋ณด๋ด๊ธฐ๋ฅผ ์ง์ํ๋ ์ธ๊ธฐ ์๋ API ํ ์คํธ ๋๊ตฌ์ ๋๋ค.
- Insomnia: OpenAPI ์ ์ ๊ฐ์ ธ์ค๊ธฐ ๋ฐ ๋ด๋ณด๋ด๊ธฐ๋ฅผ ์ง์ํ๊ณ API ํ ์คํธ ๋ฐ ๋๋ฒ๊น ์ ์ํ ๊ณ ๊ธ ๊ธฐ๋ฅ์ ์ ๊ณตํ๋ ๋ ๋ค๋ฅธ API ํด๋ผ์ด์ธํธ์ ๋๋ค.
- ์จ๋ผ์ธ ์ ํจ์ฑ ๊ฒ์ฌ๊ธฐ: ์ฌ๋ฌ ์น์ฌ์ดํธ์์ ์จ๋ผ์ธ OpenAPI ์ ํจ์ฑ ๊ฒ์ฌ ์๋น์ค๋ฅผ ์ ๊ณตํฉ๋๋ค.
ํจ๊ณผ์ ์ธ OpenAPI ์ ์ ์์ฑ์ ์ํ ๋ชจ๋ฒ ์ฌ๋ก
OpenAPI ์ฌ์์ ์ด์ ์ ๊ทน๋ํํ๋ ค๋ฉด ๋ค์ ๋ชจ๋ฒ ์ฌ๋ก๋ฅผ ๋ฐ๋ฅด์ญ์์ค:
๋ช ํํ๊ณ ๊ฐ๊ฒฐํ ์ค๋ช ์ฌ์ฉ
๋ชจ๋ API ์๋ํฌ์ธํธ, ๋งค๊ฐ๋ณ์ ๋ฐ ์๋ต์ ๋ํด ๋ช ํํ๊ณ ๊ฐ๊ฒฐํ ์ค๋ช ์ ์ ๊ณตํ์ญ์์ค. ์ด๋ ๊ฐ๋ฐ์๊ฐ API์ ๋ชฉ์ ๊ณผ ๊ธฐ๋ฅ์ ์ดํดํ๋ ๋ฐ ๋์์ด ๋ฉ๋๋ค. ์๋ฅผ ๋ค์ด, "id" ๋์ "์ฌ์ฉ์ ID" ๋๋ "์ ํ ID"๋ฅผ ์ฌ์ฉํ์ฌ ๋ ๋ง์ ์ปจํ ์คํธ๋ฅผ ์ ๊ณตํ์ญ์์ค.
์ผ๊ด๋ ๋ช ๋ช ๊ท์น ์ค์
API ์๋ํฌ์ธํธ, ๋งค๊ฐ๋ณ์ ๋ฐ ๋ฐ์ดํฐ ๋ชจ๋ธ์ ๋ํ ์ผ๊ด๋ ๋ช ๋ช ๊ท์น์ ์๋ฆฝํ์ญ์์ค. ์ด๋ API ์ ์๋ฅผ ๋ ์ฝ๊ฒ ์ดํดํ๊ณ ์ ์ง๋ณด์ํ ์ ์๊ฒ ํฉ๋๋ค. ๋ฐ์ดํฐ ๋ชจ๋ธ ์ด๋ฆ์๋ ํ์ค์นผ์ผ์ด์ค(PascalCase, ์: UserProfile)๋ฅผ, ๋งค๊ฐ๋ณ์ ์ด๋ฆ์๋ ์นด๋ฉ์ผ์ด์ค(camelCase, ์: userId)๋ฅผ ์ฌ์ฉํ๋ ๊ฒ์ ๊ณ ๋ คํ์ญ์์ค.
์ฌ์ฌ์ฉ ๊ฐ๋ฅํ ์ปดํฌ๋ํธ ์ฌ์ฉ
์ปดํฌ๋ํธ(Components) ์น์ ์ ํ์ฉํ์ฌ ์คํค๋ง, ๋งค๊ฐ๋ณ์, ์๋ต๊ณผ ๊ฐ์ ์ฌ์ฌ์ฉ ๊ฐ๋ฅํ ๊ฐ์ฒด๋ฅผ ์ ์ํ์ญ์์ค. ์ด๋ API ์ ์์ ์ผ๊ด์ฑ์ ๋์ด๊ณ ์ค๋ณต์ ์ค์ ๋๋ค.
์์ ๊ฐ ์ ๊ณต
๋งค๊ฐ๋ณ์ ๋ฐ ์๋ต์ ๋ํ ์์ ๊ฐ์ ํฌํจํ์ฌ ๊ฐ๋ฐ์๊ฐ ์์ ๋ฐ์ดํฐ ํ์์ ์ดํดํ๋ ๋ฐ ๋์์ ์ฃผ์ญ์์ค. ์ด๋ ํตํฉ ์๊ฐ์ ํฌ๊ฒ ๋จ์ถํ๊ณ ์ค๋ฅ๋ฅผ ๋ฐฉ์งํ ์ ์์ต๋๋ค. ์๋ฅผ ๋ค์ด, ๋ ์ง ๋งค๊ฐ๋ณ์์ ๊ฒฝ์ฐ "2023-10-27"๊ณผ ๊ฐ์ ์์ ๋ฅผ ์ ๊ณตํ์ฌ ์์ ํ์์ ๋ช ํํ ํ์ญ์์ค.
์ ์ ํ ๋ฐ์ดํฐ ์ ํ ์ฌ์ฉ
๋ชจ๋ ๋งค๊ฐ๋ณ์์ ์์ฑ์ ๋ํด ์ฌ๋ฐ๋ฅธ ๋ฐ์ดํฐ ์ ํ์ ์ง์ ํ์ญ์์ค. ์ด๋ ๋ฐ์ดํฐ ๋ฌด๊ฒฐ์ฑ์ ๋ณด์ฅํ๊ณ ์๊ธฐ์น ์์ ์ค๋ฅ๋ฅผ ๋ฐฉ์งํ๋ ๋ฐ ๋์์ด ๋ฉ๋๋ค. ์ผ๋ฐ์ ์ธ ๋ฐ์ดํฐ ์ ํ์๋ string, integer, number, boolean, array๊ฐ ์์ต๋๋ค.
์ค๋ฅ ์๋ต ๋ฌธ์ํ
HTTP ์ํ ์ฝ๋์ ์ค๋ฅ ์ค๋ช ์ ํฌํจํ์ฌ ๊ฐ๋ฅํ ๋ชจ๋ ์ค๋ฅ ์๋ต์ ๋ช ํํ๊ฒ ๋ฌธ์ํํ์ญ์์ค. ์ด๋ ๊ฐ๋ฐ์๊ฐ ์ค๋ฅ๋ฅผ ์ ์์ ์ผ๋ก ์ฒ๋ฆฌํ๊ณ ๋ ๋์ ์ฌ์ฉ์ ๊ฒฝํ์ ์ ๊ณตํ๋ ๋ฐ ๋์์ด ๋ฉ๋๋ค. ์ผ๋ฐ์ ์ธ ์ค๋ฅ ์ฝ๋์๋ 400(์๋ชป๋ ์์ฒญ), 401(๊ถํ ์์), 403(๊ธ์ง๋จ), 404(์ฐพ์ ์ ์์), 500(๋ด๋ถ ์๋ฒ ์ค๋ฅ)์ด ํฌํจ๋ฉ๋๋ค.
API ์ ์ ์ต์ ์ํ ์ ์ง
API๊ฐ ๋ฐ์ ํจ์ ๋ฐ๋ผ OpenAPI ์ ์๋ฅผ ์ต์ ์ํ๋ก ์ ์งํ์ญ์์ค. ์ด๋ ๋ฌธ์๊ฐ API์ ํ์ฌ ์ํ๋ฅผ ์ ํํ๊ฒ ๋ฐ์ํ๋๋ก ๋ณด์ฅํฉ๋๋ค. API๊ฐ ๋ณ๊ฒฝ๋ ๋๋ง๋ค API ์ ์๋ฅผ ์๋์ผ๋ก ์ ๋ฐ์ดํธํ๋ ํ๋ก์ธ์ค๋ฅผ ๊ตฌํํ์ญ์์ค.
์ ํจ์ฑ ๊ฒ์ฌ ์๋ํ
CI/CD ํ์ดํ๋ผ์ธ์ OpenAPI ์ ํจ์ฑ ๊ฒ์ฌ๋ฅผ ํตํฉํ์ฌ API ์ ์์ ๋ํ ๋ชจ๋ ๋ณ๊ฒฝ ์ฌํญ์ด ์ ํจํ๊ณ ์กฐ์ง์ ํ์ค์ ์ค์ํ๋์ง ํ์ธํ์ญ์์ค. ์ด๋ ์ค๋ฅ๋ฅผ ๋ฐฉ์งํ๊ณ API ์ํ๊ณ ์ ๋ฐ์ ์ผ๊ด์ฑ์ ๋ณด์ฅํ๋ ๋ฐ ๋์์ด ๋ฉ๋๋ค.
OAS ๋ฒ์ : ์ฌ๋ฐ๋ฅธ ๋ฒ์ ์ ํํ๊ธฐ
OpenAPI ์ฌ์์ ์ฌ๋ฌ ๋ฒ์ ์ ๊ฑฐ์ณ ๋ฐ์ ํด ์์ต๋๋ค. ์ค๋๋ ๊ฐ์ฅ ์ผ๋ฐ์ ์ผ๋ก ์ฌ์ฉ๋๋ ๋ฒ์ ์ 3.0.x์ 3.1.x์ ๋๋ค. ๋ ๋ฒ์ ๋ชจ๋ ๋์ผํ ํต์ฌ ์์น์ ๊ณต์ ํ์ง๋ง ๋ช ๊ฐ์ง ์ฃผ์ ์ฐจ์ด์ ์ด ์์ต๋๋ค:
- OpenAPI 3.0.x: ๋๋ฆฌ ์ฑํ๋์์ผ๋ฉฐ ๋๊ท๋ชจ ๋๊ตฌ ์ํ๊ณ์์ ์ง์๋ฉ๋๋ค. ์์ ์ ์ด๊ณ ์ฑ์ํ ๋ฒ์ ์ผ๋ก ํธํ์ฑ์ด ๋ฐ์ด๋ฉ๋๋ค.
- OpenAPI 3.1.x: ์ต์ ๋ฒ์ ์ผ๋ก, JSON ์คํค๋ง์ ๋ํ ๋ ๋์ ์ง์๊ณผ ๋ ์ ์ฐํ ๋ฐ์ดํฐ ๋ชจ๋ธ๋ง์ ํฌํจํ ์ฌ๋ฌ ๊ฐ์ ์ฌํญ์ ๋์ ํ์ต๋๋ค. ๋ํ ์ด์ ๋ฒ์ ์ ์ผ๋ถ ์ ํ ์ฌํญ์ ์ ๊ฑฐํ์ต๋๋ค.
์ฌ๋ฐ๋ฅธ ๋ฒ์ ์ ์ ํํ๋ ๊ฒ์ ํน์ ์๊ตฌ ์ฌํญ๊ณผ ์ฌ์ฉ ์ค์ธ ๋๊ตฌ์ ๋ฐ๋ผ ๋ค๋ฆ ๋๋ค. ์ ํ๋ก์ ํธ๋ฅผ ์์ํ๋ ๊ฒฝ์ฐ ์ผ๋ฐ์ ์ผ๋ก OpenAPI 3.1.x๊ฐ ๊ถ์ฅ๋ฉ๋๋ค. ๊ทธ๋ฌ๋ 3.1.x๋ฅผ ์์ ํ ์ง์ํ์ง ์์ ์ ์๋ ๊ธฐ์กด ๋๊ตฌ๋ก ์์ ํ๋ ๊ฒฝ์ฐ OpenAPI 3.0.x๊ฐ ๋ ๋์ ์ ํ์ผ ์ ์์ต๋๋ค.
์ค์ ์ธ๊ณ์์์ OpenAPI ํ์ฉ ์ฌ๋ก
๋ค์ํ ์ฐ์ ๋ถ์ผ์ ๋ง์ ์กฐ์ง์ด API ๋ฌธ์ ๋ฐ ๊ฐ๋ฐ ํ๋ก์ธ์ค๋ฅผ ๊ฐ์ ํ๊ธฐ ์ํด OpenAPI ์ฌ์์ ์ฑํํ์ต๋๋ค. ๋ช ๊ฐ์ง ์๋ ๋ค์๊ณผ ๊ฐ์ต๋๋ค:
- ๊ธ์ต ์๋น์ค: ์ํ ๋ฐ ๊ธ์ต ๊ธฐ๊ด์ ๊ฒฐ์ API๋ฅผ ๋ฌธ์ํํ๊ธฐ ์ํด OpenAPI๋ฅผ ์ฌ์ฉํ์ฌ ์ 3์ ๊ฐ๋ฐ์๊ฐ ์์คํ ๊ณผ ํตํฉํ ์ ์๋๋ก ํฉ๋๋ค. ์ด๋ ํ์ ์ ์ธ ๊ธ์ต ์ ํ๋ฆฌ์ผ์ด์ ๊ฐ๋ฐ์ ์ด์งํฉ๋๋ค.
- ์ ์ ์๊ฑฐ๋: ์ ์ ์๊ฑฐ๋ ํ๋ซํผ์ ์ ํ API๋ฅผ ๋ฌธ์ํํ๊ธฐ ์ํด OpenAPI๋ฅผ ์ฌ์ฉํ์ฌ ๊ฐ๋ฐ์๊ฐ ๋ง์ผํ๋ ์ด์ค, ๊ฐ๊ฒฉ ๋น๊ต ์น์ฌ์ดํธ ๋ฐ ๊ธฐํ ์ ํ๋ฆฌ์ผ์ด์ ์ ์ํ ํตํฉ์ ๊ตฌ์ถํ ์ ์๋๋ก ํฉ๋๋ค.
- ์ฌํ ๋ฐ ๊ด๊ด: ์ฌํ์ฌ๋ ์์ฝ API๋ฅผ ๋ฌธ์ํํ๊ธฐ ์ํด OpenAPI๋ฅผ ์ฌ์ฉํ์ฌ ์ฌํ์ฌ ๋ฐ ๊ธฐํ ํํธ๋๊ฐ ์์คํ ๊ณผ ํตํฉํ ์ ์๋๋ก ํฉ๋๋ค.
- ํฌ์ค์ผ์ด: ํฌ์ค์ผ์ด ์ ๊ณต์ ์ฒด๋ ํ์ ๋ฐ์ดํฐ API๋ฅผ ๋ฌธ์ํํ๊ธฐ ์ํด OpenAPI๋ฅผ ์ฌ์ฉํ์ฌ ๊ฐ๋ฐ์๊ฐ (๊ฐ์ธ ์ ๋ณด ๋ณดํธ ๊ท์ ์ ์ค์ํ๋ฉด์) ํ์ ์ ๋ณด์ ์ก์ธ์คํ๊ณ ๊ด๋ฆฌํ๊ธฐ ์ํ ์ ํ๋ฆฌ์ผ์ด์ ์ ๊ตฌ์ถํ ์ ์๋๋ก ํฉ๋๋ค.
OpenAPI๋ฅผ ํตํ API ๋ฌธ์์ ๋ฏธ๋
OpenAPI ์ฌ์์ API ์ํ๊ณ์ ๋ณํํ๋ ์๊ตฌ๋ฅผ ์ถฉ์กฑ์ํค๊ธฐ ์ํด ์ง์์ ์ผ๋ก ๋ฐ์ ํ๊ณ ์์ต๋๋ค. ๋ฏธ๋ ๋ํฅ์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค:
- ํฅ์๋ ๋ณด์ ๊ธฐ๋ฅ: ๋ณด์ ์ ์ ๋ฐ ์ธ์ฆ ๋ฐฉ๋ฒ์ ์ง์์ ์ธ ๊ฐ์ .
- GraphQL ์ง์: API์ฉ ์ฟผ๋ฆฌ ์ธ์ด์ธ GraphQL๊ณผ์ ์ ์ฌ์ ํตํฉ.
- AsyncAPI ํตํฉ: ์ด๋ฒคํธ ๊ธฐ๋ฐ API๋ฅผ ์ํ ์ฌ์์ธ AsyncAPI์์ ๊ธด๋ฐํ ์ฐ๊ณ.
- AI ๊ธฐ๋ฐ ๋ฌธ์ํ: ์ธ๊ณต ์ง๋ฅ์ ํ์ฉํ์ฌ API ๋ฌธ์๋ฅผ ์๋์ผ๋ก ์์ฑํ๊ณ ์ ์ง ๊ด๋ฆฌ.
๊ฒฐ๋ก
OpenAPI ์ฌ์์ ์ค๋๋ ์ ์ฐ๊ฒฐ๋ ์ธ๊ณ์์ API๋ฅผ ์ค๊ณ, ๋ฌธ์ํ ๋ฐ ์ฌ์ฉํ๋ ๋ฐ ํ์์ ์ธ ๋๊ตฌ์ ๋๋ค. OAS๋ฅผ ์ฑํํ๊ณ ๋ชจ๋ฒ ์ฌ๋ก๋ฅผ ๋ฐ๋ฅด๋ฉด ๊ฐ๋ฐ์ ๊ฒฝํ์ ๊ฐ์ ํ๊ณ , API ๊ฒ์ ๊ฐ๋ฅ์ฑ์ ๋์ด๊ณ , API ๊ฑฐ๋ฒ๋์ค๋ฅผ ๋จ์ํํ๊ณ , ๊ฐ๋ฐ ๋น์ฉ์ ์ ๊ฐํ ์ ์์ต๋๋ค. ๋ด๋ถ์ฉ์ด๋ ์ธ๋ถ์ฉ์ด๋ API๋ฅผ ๊ตฌ์ถํ๋ ๊ฒฝ์ฐ OpenAPI ์ฌ์์ ๋ ๊ฐ๋ ฅํ๊ณ ์์ ์ ์ด๋ฉฐ ์ฌ์ฉ์ ์นํ์ ์ธ API๋ฅผ ๋ง๋๋ ๋ฐ ๋์์ด ๋ ์ ์์ต๋๋ค.
OpenAPI ์ฌ์์ ํ์ ๋ฐ์๋ค์ฌ API์ ์ ์ฌ๋ ฅ์ ์ต๋ํ ๋ฐํํ์ญ์์ค. ๊ฐ๋ฐ์(๊ทธ๋ฆฌ๊ณ ๋น์ฆ๋์ค)๊ฐ ๊ฐ์ฌํ ๊ฒ์ ๋๋ค.