# Reference
LINE Engineering - ๋ฌธ์ ์์ง๋์ด๋ง๊ณผ API ๋ฌธ์ํ by ์ ์ ์
https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation/
API ๋ ํผ๋ฐ์ค ๋ฌธ์ ์ ์ ํธ๋ ๋ ๋ฐ ๋๊ตฌ ์กฐ์ฌ by ์ง๋จ๋ก๋ณดํธ
https://jsonobject.tistory.com/355
๋ฐฑ์๋๊ฐ ์ด์ ๋๋ ํด์ค์ผ ํจ - 6.API ์คํ ์ค๊ณ์ ๋ฌธ์ํ ๋ฐฉ์ ๊ฒฐ์ - (2) by city7310
Restful API ๋ฌธ์ ์์ฑ by Peter Kim
TISTORY OpenAPI
https://tistory.github.io/document-tistory-apis/apis/
0) ํ์ต๊ฐ์
์๋๋ฐ๋งต ์๋น์ค๊ฐ ์ง์ง ์ผ๋ง ๋จ์ง ์์ Backend API์ ์ ๋ฆฌ๊ฐ ํ์ํ ์์ ์ด ๋์์ต๋๋ค.
(์ฌ์ค ์ด๋ฏธ ํด๋จ์ด์ผ ํ์ง๋ง ๋๋ฌด ๋ฐ๋น ์ ๋ฏธ๋ค๋์)
์ด์ ๊น์ง๋ Backend API ๋ฌธ์๋ฅผ ๋ค๋ฅธ ํ์์ด ์์ฑํ๊ฑฐ๋ ๊ทธ๋ํฝ์ผ๋ก ์ ๋ฆฌํด์ ์ค๋ณธ ๊ฒฝํ๋ฐ์ ์์ด์, ์ด๋ฒ ๊ธฐํ์ Swagger๋ฅผ ์ด์ฉํ์ฌ ์ผ๋ฐ์ ๋ฐ๋ก ๊ณต๊ฐํ ์ ์๋ API๋ฅผ ๋ง๋ค์ด๋ณด๊ณ ์ ํ์์ต๋๋ค.
1) API ๋ฌธ์ํ๋๊ตฌ ์ ์
API ๋ ํผ๋ฐ์ค๋ฅผ ์์ฑํ๊ธฐ ์ํ ๋๊ตฌ๋ ์ฌ๋ฌ๊ฐ์ง๊ฐ ์กด์ฌํฉ๋๋ค.
-------
1) Slate
๋งํฌ๋ค์ด ๊ธฐ๋ฐ ๋ฌธ์ํฌ๋ฉง ๋ฐ ๋ฐ์ํ ๋ ๋๋ฌ ์ ๊ณต.
๋ฌธ์ ํฌ๋งท์ด ์ง๊ด์ ์ด๋ฉฐ ๋จ์.
1๊ฐ ํ ๋ง / 3๊ฐ ํจ๋ ๋์์ธ
ํ์ต๋์ด๋ ๋ฎ์ | ๊ฒฐ๊ณผ๋ฌผ ์ธ๋ จ๋จ (์ต์ ๋ ธ๋ ฅ ์ต๋ ๊ฒฐ๊ณผ)
2) API Blueprint
Slate์ ์ ์ฌ.
๋ฌธ์ ํํ๊ฐ๋ฅ๋ฒ์ ๋ค์.
๋ ๋๋ฌ ์์ (Third-party ๋ ๋๋ฌ ์ฌ์ฉ์ด ํ์ํจ (ex: Aglio))
+) Aglio: 5๊ฐ ํ ๋ง / 2, 3ํจ๋ ๋์์ธ ์ ๊ณต
ํ์ต๋์ด๋ ์ฝ๊ฐ ๋์ (< Slate)
3) Swagger
๊ฐ์ฅ ์ ๋ช
JSON & RAML ๊ธฐ๋ฐ ๋ฌธ์ํฌ๋งท ์ ๊ณต
๊ฐ๋ ฅํ REST API ์ค๊ณ์ฒ ํ ๊ฐ์ => ๋น์ค์ ์๋น์ค: ์ ์ฉ๋ถ๊ฐ
์์ฒด ๋ ๋๋ฌ ์กด์ฌ (Swagger UI), ์ ๋ช ํ Third-party ๋ ๋๋ฌ ์กด์ฌ (ReDoc, 3ํจ๋ ๋์์ธ)
4) GitBook
๊น๋ํ UI ์ ๊ณต
Git์ commit / merge๊ฐ ์กด์ฌ -> ๋ฌธ์ ๋ฒ์ ๊ด๋ฆฌ ๊ฐ๋ฅ (=์ ๋ฐ์ดํธ ๋ด์ญ ํ์ธ ์ฉ์ด)
ํ ์คํธ ์์ฒญ / ์๋ต ์ฌ์ฉ ๋ถ๊ฐ
ํ์ด ์ฌ์ฉํ ๊ฒฝ์ฐ ์ ๋ฃ (๊ฐ์ธ์ ๋ฌด๋ฃ)
-------
์ ๋ ์ด์ค GitBook์ ์ฌ์ฉํ๊ณ , ์ด์ ๋ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
1) API๋ก ๊ณต๊ฐํ๋ ์ ๋ณด๋ฅผ ์ฌ์ฉํ ๋์์ด ์ ํ์ ์ (์์ฃผ๋ํ๊ต ๋ด์์ ์ธ๊ทผ ์์์ ์ ๋ณด๋ฅผ ํ์ฉํ ๊ฐ๋ฐ ํ๋ก์ ํธ๋ฅผ ์งํํ๊ณ ์ ํ๋ ํ์ฐ)
2) ํ ์คํธ ์์ฒญ์ ์ง์ํด์ผํ๋ ํ์์ฑ์ด ํฌ์ง ์์ (1๊ณผ ์๋)
3) ๊ฐ์ธ ํ๋ก์ ํธ์ด๋ฏ๋ก API ๋ฌธ์ ์์ฑ์ด ๋ฌด๋ฃ
2) Gitbook ๋๋ฌ๋ณด๊ธฐ
GitBook์ ๊ฐ์ ํ๊ณ ๋ ๋ค API Docs๋ฅผ ์ ํ ํ ์งํํ์ต๋๋ค.
API๋ฌธ์ ์์ฑ์ด ์๋ฃ๋์์ต๋๋ค. ์์ด ๋ง์ ํ๋ฒ์ ์์ฑํ์ง ๋ชปํ๊ณ , user api๋ง ์ ๋ก๋ ํ์ต๋๋ค.
์ง์์ ์ผ๋ก ์ ๋ฐ์ดํธ ํ๋ฉฐ ์๋น์ค ๊ณต๊ฐ ์งํ ๊ณต๊ฐ ํ ์์ ์ ๋๋ค.
https://nate-crema.gitbook.io/aj-mealmap-api/
--------|Updated
2021.11.13 | ๋ฌธ์ ์ ๊ท์์ฑ